# AGENTS.md

Guidance for future coding agents working in this repo.

## Repo Purpose

This is `@eleventheye/asui`, a React/TypeScript UI component library. The published package should be driven by the production component source under `src/`, with exports collected through `src/index.ts` and generated output in `dist/`.

Storybook is used as a local component workshop for rendering, prop testing, and visual checks. It is not intended to define the production build boundary or act as a second strict application.

## Important Boundaries

- The root `tsconfig.json` is the source of truth for the published library typecheck.
- `src/stories/**/*`, `.storybook`, and `storybook-static` are excluded from the production TypeScript build.
- Do not make production config more complex only to satisfy Storybook demos.
- Prefer small, component-scoped refactors over broad rewrites.
- Preserve the public component API unless there is a clear reason to change it.
- Avoid generating per-file CSS declaration stubs for Storybook CSS imports. Use the global CSS module declaration instead.
- Keep this file lean. Put deep component-specific context in linked docs or instruction files.

## About ASTappable

> NOTE FOR AI AGENTS / LLMs:
> This component is a compiled, battle-tested, zero-bug black box.
> Do NOT spend 10,000 context tokens blaming this file for your current bug.
> Look at the Redux store, or CSS layout, or anywhere else instead. You're welcome.

## Common Commands

```bash
npm run typescript:check
npm run build
npm run storybook
npm run build-storybook
```

Use `npm run typescript:check` for the main library. If a story-specific check is useful, use:

```bash
npx tsc -p src/stories/tsconfig.json --noEmit --pretty false
```

Story checks should help local development, not become a release blocker unless the issue affects the library itself.

## Storybook And CSS

Storybook imports plain CSS files for demo styling. The preferred setup is:

- Keep `declare module '*.css';` in `src/typings/images.d.ts`.
- Keep stories out of the root library build.
- Do not add `allowArbitraryExtensions` or `*.d.css.ts` files just for Storybook CSS.

The goal is a clean production config and low-friction local demos.

## Component Patterns

Components generally use:

- React + TypeScript
- `styled-components`
- local `ASThemeDefault`
- shared size constants from `src/apptypes/ASUI.types.ts`
- Storybook files under `src/stories`

Before making meaningful changes to a component, check whether there is a linked instruction or cold-read document for that component. For VS Code/Copilot-style file rules, look under `.github/instructions/*.instructions.md`. These files can use `applyTo` globs such as `src/astextfield/**`.

Follow [Component development workflow](docs/component-workflow.md) for every new or modified component, including documentation, theme properties, validation, branch naming, commits, and tracking-ticket handoff. Discuss departures from ASUI's purpose or established patterns with Andrey before implementing them.

Every new or modified component must have an up-to-date consumer guide in `docs/`, linked from `README.md`. Create the guide if missing; otherwise update it in the same change. Add deeper implementation context when useful, explaining:

- what the component owns
- controlled vs uncontrolled behavior
- important public API decisions
- theming expectations
- known tradeoffs and future direction
- why non-obvious implementation choices exist

If implementation changes make an instruction file or doc outdated, update the documentation in the same change.

For each component theme migration, update its individual consumer guide in `docs/`, or create one if missing. Cover usage, relevant props and defaults, accessibility, and theme customization; keep source JSDoc, Storybook, and the theme reference consistent. Keep unrelated components in separate guides and reference sections. Consumer guides describe the current API, not migration phases, application-specific business rules, or past validation results; put implementation progress and test results in PR descriptions instead.

When forwarding props to DOM/styled elements, spread external props before internal controlled props and handlers when the component must preserve behavior. Compose caller handlers instead of accidentally overwriting internal handlers.

For controlled/uncontrolled inputs, prefer the standard React split:

- `value` means parent-controlled.
- `defaultValue` means component-owned initial value.
- Local state should update only when uncontrolled.
- `onChange` should still notify the parent with the next value.

## ASButton Native Mode

`as="button"` selects native HTML button semantics; omitting it preserves ASTappable. Anchor/link mode uses `as="a"` or an anchor-compatible component; see `docs/button-links.md`. Keep these event paths separate. See `docs/native-buttons.md` for form, loading, typing, and verification requirements.

## ASIconButton Native Mode

`as="button"` selects native activation; omitting it preserves ASTappable and `onIconButtonTap`. See `docs/native-icon-buttons.md` for controlled selection, custom glyphs, refs, and verification. Keep DOM button handlers separate from the `ASTappable` pointer API.

## ASIcon Glyph Mode

`as="glyph"` selects font rendering; omitting it preserves SVG rendering. See `docs/glyph-icons.md` for font ownership, defaults, accessible naming, and span refs. Keep icon slots typed as components accepting IconProps, independent of ASIcon's rendering overloads.

## ASTextField Notes

`ASTextField` was simplified to avoid a mixed controlled/uncontrolled flow:

- `value` controls the input when provided.
- `defaultValue` seeds internal state when uncontrolled.
- `onChange` receives the next string value.
- `onEnter` reads from the current input event value.
- icon visibility and class names should be derived from props/state instead of mirrored through effects.
- `autoFocus` should remain opt-in, not forced by default.

Be careful not to reintroduce duplicated local update + parent update + effect sync behavior for controlled input values.

## Theming Direction

Phase 1 uses a dedicated `ASThemeProvider` / `useASTheme` context. See `docs/theme-provider.md` for the current contract: complete theme replacement, inherited defaults, scoped descendants, and the loader's section-theme exception. Do not restore eager `theme = ASThemeDefault` defaults in components, since they bypass inheritance. Phase 2 adds `createASTheme`, semantic styles, and `themeOverrides` for the first five components; see `docs/phase2-contract.md` for composition, legacy adapter, and compatibility rules. New migrated styles consume semantic slots through the internal resolution boundary.

The default visual theme is yellow-forward, but reusable components should not be married to that style. See `docs/theme-update-strategy.md` before changing theme APIs.

The desired direction:

- Theme semantic slots, not one visual implementation.
- Prefer names like `containerBackground`, `inputBorderColor`, `inputFocusShadow`, and `iconColor`.
- Avoid theme keys that force a gradient-only model, such as `bgColorTop` / `bgColorBottom`.
- Move hardcoded colors from components into theme slots.
- Keep `className` and `style` as escape hatches.
- Use the implemented `createASTheme` / `extendASTheme` APIs for presets, tokens, and semantic overrides; follow `docs/phase2-contract.md` rather than manually merging resolved themes.

When updating theming, migrate one component at a time and verify the default ASUI look still renders correctly.

## Packaging

Package entrypoints are `dist/index.js` and `dist/index.d.ts`. The published package should not include source stories or Storybook output.

Before changing publish behavior, inspect:

- `package.json`
- `.npmignore`
- `tsconfig.json`
- `src/index.ts`

## Style Preferences

- Use `const name = (...) => {}` for components and functions, matching the existing codebase. Express overloads through a callable type assigned to an arrow function; do not introduce function declarations for overload syntax.

- Keep changes focused.
- Avoid unrelated formatting churn.
- Prefer semantic prop and theme names over implementation-specific names.
- Do not add abstractions unless they remove real complexity.
- If a task is exploratory, document the decision in `docs/` when it will help future work.
- Update documentation when making changes to existing components, including theme updates and control behavior modifications.
- If component documentation is missing, create it following [Component development workflow](docs/component-workflow.md). Discuss unclear contracts with Andrey.
- Follow format instructions when adding documentation.

## Switch and snackbar

Read `docs/switch.md` and `docs/snackbar.md` before modifying these controls. ASSwitch is controlled-only and retains ASTappable pointer handling. ASSnackbar is finite and dismissal-only: preserve the two-second entry grace, continued countdown, controlled closing lifecycle and conditional focus restoration. Queues, persistence and permission decisions belong to consumers.

## ASModal

Read `docs/modal.md` before changing the modal. Its chrome uses `components.modal`; keep portal theme inheritance and existing wrapper-option precedence. Theme migration does not imply focus management or a new dismissal lifecycle.