|
|
# CLAUDE.md
|
|
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
|
|
## Build/Test Commands
|
|
|
|
|
|
```bash
|
|
|
npm run dev # Start dev server
|
|
|
npm run build # Production build (static site via adapter-static)
|
|
|
npm run test # Run all tests once
|
|
|
npm run test:unit # Run tests in watch mode
|
|
|
npx vitest run src/lib/ling/test/ling.test.ts # Run single test file
|
|
|
npx vitest run -t "describe name" # Run tests matching pattern
|
|
|
npm run check # Type check with svelte-check
|
|
|
npm run lint # Check formatting with Prettier
|
|
|
npm run format # Auto-format with Prettier
|
|
|
```
|
|
|
|
|
|
## Code Style
|
|
|
|
|
|
- Tabs for indentation, single quotes, no trailing commas, 100 char print width (Prettier)
|
|
|
- Spanish comments in code are acceptable
|
|
|
- Svelte 5 runes mode enforced globally (`svelte.config.js` `dynamicCompileOptions`)
|
|
|
- DOM event handlers: lowercase (`onclick`, `onfocus`). User callbacks: camelCase (`onComplete`, `onInteractOutside`)
|
|
|
- State fields: `$state()` without `#`. Derived: `readonly x = $derived.by(...)`
|
|
|
- Boolean attrs: always use helpers (`boolToTrueOrUndef`, `boolToEmptyStrOrUndef`, `boolToStr`) — never ternaries
|
|
|
|
|
|
## Path Aliases
|
|
|
|
|
|
Aliases must be synced in BOTH `svelte.config.js` AND `vite.config.ts`:
|
|
|
|
|
|
| Alias | Target |
|
|
|
| ----------------------- | ------------------------------------------------------ |
|
|
|
| `@/` | `src/` |
|
|
|
| `@/ling` | `src/lib/ling` (i18n) |
|
|
|
| `@/logr` | `src/lib/logr` (logging) |
|
|
|
| `@/glob` | `src/lib/glob` (legacy; do not use for new code) |
|
|
|
| `@/actx` | `src/lib/actx` (app context) |
|
|
|
| `@/uiux` | `src/lib/uiux` |
|
|
|
| `$uix` | `src/uix` (UI layers) |
|
|
|
| `$terra` | `src/uix/terra` (headless primitives) |
|
|
|
| `$terra/utils` | `src/uix/terra/utils/sound.svelte.ts` |
|
|
|
| `$terra/system` | `src/uix/terra/system/exports.ts` |
|
|
|
| `$terra/external/dates` | `src/uix/terra/external/dates/sound.svelte.ts` |
|
|
|
| `$lib` | `src/lib` |
|
|
|
| `$lib/util/dias` | `src/lib/util/dias` (date/time library — canonical) |
|
|
|
|
|
|
## Vitest Two-Project Structure
|
|
|
|
|
|
`vite.config.ts` defines two test projects:
|
|
|
|
|
|
- **client**: Browser tests via Playwright for `*.svelte.{test,spec}.{js,ts}`
|
|
|
- **server**: Node environment for `*.{test,spec}.{js,ts}` (excludes svelte tests)
|
|
|
|
|
|
## Architecture: Three-Layer UI System
|
|
|
|
|
|
```
|
|
|
terra → headless primitives: behavior, accessibility, data-* contracts, context
|
|
|
air → visual layer on top of terra: tokens, themes, recipes, styled components
|
|
|
glob → domain logic: dates, numbers, currency, units, locale
|
|
|
```
|
|
|
|
|
|
The dependency flows one way: `air` → `terra`. Terra never imports from air.
|
|
|
|
|
|
### terra (`src/uix/terra/`)
|
|
|
|
|
|
Headless primitive library. Each component follows `Element.SubElement` pattern (`Dialog.Root`, `Dialog.Trigger`, `Dialog.Content`).
|
|
|
|
|
|
**Key patterns:**
|
|
|
|
|
|
- Thin `.svelte` wrappers + logic in `*.svelte.ts` State classes
|
|
|
- State classes use `static create()` for context registration, `createComposed()` for internal composition without context
|
|
|
- Reactive system: `Active<T>`, `State<T>`, `readableActive()`, `writableActive()` — values travel as boxes with `.current`
|
|
|
- Context via `createTerraContext()` (wraps runed's `Context`)
|
|
|
- Props merging: `mergeProps(restProps, state.props)` in every wrapper
|
|
|
- `data-*` attrs are formal public API, validated via `assertDataContract()` against `utils/contracts.ts`
|
|
|
- `child` snippet replaces the rendered node; `children` fills the interior
|
|
|
|
|
|
**Structure:**
|
|
|
|
|
|
- `[component]/components/` — Svelte wrappers
|
|
|
- `[component]/types.ts` — public props
|
|
|
- `[component]/*.svelte.ts` — State classes
|
|
|
- `[component]/exports.ts` + `sound.svelte.ts` — barrel exports
|
|
|
- `layers/` — shared infra (portal, floating, presence, focus-scope, dismissible, escape, scroll)
|
|
|
- `dom/` — browser-dependent utils (focus, roving focus, arrow navigation)
|
|
|
- `utils/` — pure helpers (state system, attrs, merge-props, events, keyboard, css, datetime)
|
|
|
- `system/` — `TerraConfig` for cross-cutting services (translator, formatters, logger, dir, portalTo)
|
|
|
- `external/dates/` — adapter boundary for date library
|
|
|
|
|
|
**Import rules within terra:** use `$terra/utils` or relative paths internally, never `$uix/terra`.
|
|
|
|
|
|
### air (`src/uix/air/`)
|
|
|
|
|
|
Visual layer built on terra. Consumes terra's public anatomy and `data-*` attrs — never internal classes or incidental DOM structure.
|
|
|
|
|
|
**Three-level token system:**
|
|
|
|
|
|
1. **Primitive tokens** (`tokens/primitive.css`) — absolute scale values, never used directly by components
|
|
|
2. **Semantic tokens** (`tokens/semantic.css`) — theme-aware, switch via `[data-theme]`
|
|
|
3. **Component tokens** (`tokens/components/*.css`) — scoped per component (`--air-button-*`), the only level component CSS writes
|
|
|
|
|
|
**Token naming:**
|
|
|
|
|
|
- Public: `--air-{component}-*` (stable, overridable)
|
|
|
- Private: `--_air-{component}-*` (implementation detail, may change)
|
|
|
|
|
|
**Contracts** (`contracts/`):
|
|
|
|
|
|
- `contract.css` — minimum semantic tokens any theme must implement
|
|
|
- `contract-categorical.css` — optional categorical color families
|
|
|
- `contract-primitives.css` — optional advanced 12-step scales
|
|
|
- `contracts/components/*.css` — per-component public token API
|
|
|
|
|
|
**CSS rules:**
|
|
|
|
|
|
- Tokens and `data-*` selectors must be global CSS (imported `.css` files), not `<style scoped>`
|
|
|
- Svelte scoped styles only for properties that don't depend on `data-*` or terra internals
|
|
|
- Components respond to terra states purely via `data-*` selectors: `[data-disabled]`, `[data-state='open']`, etc.
|
|
|
- Theme activation via `data-theme` attribute on any DOM container (supports nesting)
|
|
|
- Variant dimensions are orthogonal: `size` → dimensions, `variant` → appearance, `state` → transversal overrides
|
|
|
|
|
|
**Structure:**
|
|
|
|
|
|
- `components/` — styled wrappers over terra primitives
|
|
|
- `tokens/` — token implementation (primitive, semantic, per-component)
|
|
|
- `contracts/` — public token interfaces for theme authors
|
|
|
- `themes/` — theme implementations (base light/dark)
|
|
|
- `icons/` — icon system (`Icon` + per-icon components in `icons/lib/`)
|
|
|
|
|
|
### Internal Libraries (`src/lib/`)
|
|
|
|
|
|
- `ling` — i18n system (factory: `createLing`)
|
|
|
- `logr` — logging (factory: `createLogr`, depends on `ling`)
|
|
|
- `ext/` — App-layer reactive services: `app`, `dates`, `lang`, `money`, `nums`, `presentation`, `units`
|
|
|
- `util/dias` — canonical date/time library. Single public door at `$lib/util/dias`. `_vendor/` holds the internal implementation (Adobe Apache 2.0 vendored code) and MUST NOT be imported by consumers
|
|
|
- `glob` — legacy (pre-App-layer); do not use for new code
|
|
|
- `actx` — app context
|
|
|
- `vice` — app-level utilities
|
|
|
|
|
|
**Dates — canonical layout:**
|
|
|
|
|
|
- Value types (`CalendarDate`, `CalendarDateTime`, `Time`, `ZonedDateTime`), 9 calendars, queries, operations, parsing: all re-exported from `$lib/util/dias`
|
|
|
- All date-related `Intl` (`DateFormatter`, cache, `resolveDateOrder`, `resolveHourCycle`, placeholders, defaults) lives in `$lib/util/dias/format.ts`
|
|
|
- `ext/dates` is a thin reactive wrapper for App-level preferences (dateOrder, hourCycle) that delegates formatting to `dias`
|
|
|
- `HourCycle` is canonically numeric — `12 | 24` — matching `Intl.DateTimeFormat`'s `hour12` resolved option. Never `'12h' | '24h'`
|
|
|
- Soma consumes via `$soma/external/dates`; terra via `$terra/external/dates`. Both re-export from `dias`. Components never import `dias` directly
|
|
|
|
|
|
**Number formatting:** use `createNumr` from the App layer, NEVER raw `Intl.NumberFormat`.
|
|
|
|
|
|
### soma (`src/uix/soma/`)
|
|
|
|
|
|
Headless component library. Follows terra's architecture exactly — same patterns, same conventions. Uses `$soma` alias.
|
|
|
|
|
|
**Key patterns (must match terra):**
|
|
|
|
|
|
- Child providers reference parent as `provider`, NEVER `root`
|
|
|
- **The root export is always `Provider`, never `Root`**. Consumer writes `<Dialog.Provider>`, `<Calendar.Provider>`. `createAttrs` still uses the part name `'root'` internally — that is the DOM attribute part, not the export
|
|
|
- **Data-attr naming is canonical**: `data-{component}` (root) and `data-{component}-{part}` (sub-parts), emitted by `createAttrs`. **Never** `data-soma-*`. QuerySelectors, CSS selectors, README tables, and inline strings must all match exactly what `createAttrs` writes on the DOM — the contract validator does NOT check this (only enum values)
|
|
|
- `onChange` callbacks go in `writableActive` setter in the `.svelte` wrapper, NOT in provider Opts
|
|
|
- Translations: idlangref constants (`#?components.xxx.yyy|Fallback`) defined in the component's `langs.ts`. Root-level entries live in `src/uix/soma/core/langs.ts` under `components.{kebab-name}`. Providers call `soma?.langs.ts(IDLANGREF)` — no `resolveSomaTranslationPath` wrapper
|
|
|
- Props defined ONCE in `types.ts` (consumer API). Provider Opts only has reactive wrappers + internal fields
|
|
|
- `Soma.get()` returns the Soma config from context. `Soma.require()` throws when missing
|
|
|
- Test pages use shared layout at `src/routes/test/soma/+layout.svelte` with real `createLangs()` + `createPresentation()` + `App.create()`
|
|
|
|
|
|
**Structure:** mirrors terra exactly:
|
|
|
|
|
|
- `[component]/components/` — Svelte wrappers
|
|
|
- `[component]/types.ts` — public props with JSDoc
|
|
|
- `[component]/*-provider.svelte.ts` — Provider classes
|
|
|
- `[component]/exports.ts` + `index.ts` — barrel exports
|
|
|
- `core/` — Soma class, translator adapter, prop-resolvers, formatters
|
|
|
- `provider/` — base Provider class, context utility
|
|
|
- `layers/` — shared infra (floating, presence, focus-scope, dismissal, scroll-lock)
|
|
|
|
|
|
**Import rules within soma:** use `$soma/` alias paths, never relative paths across component boundaries.
|
|
|
|
|
|
### Test Pages
|
|
|
|
|
|
Component demos live in `src/routes/test/`. Each terra/air/soma component should have a test page demonstrating its states and variants.
|
|
|
|
|
|
Soma test pages share a layout at `src/routes/test/soma/+layout.svelte` that provides:
|
|
|
|
|
|
- Real ling instance with soma translations via `extendSomaTranslationModule`
|
|
|
- `createSomaTranslator` adapter connecting to ling
|
|
|
- Locale/dir switcher in a sticky bar
|
|
|
- `<Soma>` wrapper for all children
|
|
|
|
|
|
Test pages should NOT create their own `<Soma>` or translator — use the layout's.
|
|
|
|
|
|
## TerraConfig / Soma Integration
|
|
|
|
|
|
```svelte
|
|
|
<!-- Terra -->
|
|
|
<TerraConfig {translator} {dateTimeFormatter}>
|
|
|
<Dialog.Root />
|
|
|
</TerraConfig>
|
|
|
|
|
|
<!-- Soma -->
|
|
|
<Soma {translator} {presentation}>
|
|
|
<Dialog.Provider />
|
|
|
</Soma>
|
|
|
```
|
|
|
|
|
|
Priority chain for resolved props: explicit component prop → config context value → internal fallback. Both support nesting (child overrides parent partially).
|
|
|
|
|
|
## Key Conventions
|
|
|
|
|
|
- When creating terra components: follow the checklist in `src/uix/terra/README.md` §21
|
|
|
- When creating soma components: follow the full checklist in `src/uix/soma/COMPONENT_GUIDE.md` (rules A1–A37, 40 checklist items). Walk every item explicitly before reporting done — this is mandatory, not optional. Compare features against ark-ui, bits-ui, radix-ui, react-aria and document the gap table in the component's README. Run `npm run perm:check` (permutation runner) before shipping; instrument the demo with `data-perm-step="N"` annotations for every distinct state transition.
|
|
|
- When reading existing modules: start with `exports.ts` → `types.ts` → root `.svelte` → `*-provider.svelte.ts` → child wrappers → test page → README
|
|
|
- `$bindable()` without fallback when parent might pass `undefined`; apply defaults via coalescing (see `src/uix/terra/README.md` §13.1)
|
|
|
- Components that use Portal: consumer must manage `z-index` explicitly (layers don't impose z-indices)
|
|
|
- Every soma component ships with its own `README.md` following the format of `dialog/README.md` — anatomy, parts, props, ARIA, data-attrs, keyboard, comparison table, example
|
|
|
|
|
|
## Critical Rules
|
|
|
|
|
|
- **NEVER modify terra source code.** Terra is the reference architecture. Soma copies its patterns.
|
|
|
- **NEVER delete files without explicit instruction** ("delete", "remove", "borra", "elimina"). If ambiguous, ASK first. Reading costs nothing, deleting can be irreversible.
|
|
|
- **NEVER create fake translators** in test pages. Use real ling instances with `createSomaTranslator` + `extendSomaTranslationModule`.
|
|
|
- **READ before acting.** When told to read a file, read it. Don't interpret "léete" as "eléte".
|
|
|
- **Verify before reporting done.** Run `npm run check`, test the UI in the browser. `npm run smoke` and `npx tsx scripts/morfo-check.ts` must both be green — smoke proves 200 OK, morfo-check proves the DOM matches the morfo contract and catches `effect_update_depth_exceeded` (it shows up as "Execution context was destroyed" on the affected route — see COMPONENT_GUIDE A35).
|
|
|
- Soma audits: the two most recent are `src/uix/soma/soma-audit-2026-04-20.md` and `soma-audit-2026-04-21.md`. All their findings are resolved. Older audits (`AUDIT_1.md`, `codex_audit.md`) are historical. Read the latest audit before making architectural changes.
|
|
|
- Morfo layer: part naming is `kebab: 'provider'` for the root part (never `'root'`). `createAttrs` still emits `data-{component}` for it. See `src/uix/morfo/README.md`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
|
|
|
|
|
|
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
|
|
|
|
|
## 1. Think Before Coding
|
|
|
|
|
|
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
|
|
|
|
|
Before implementing:
|
|
|
- State your assumptions explicitly. If uncertain, ask.
|
|
|
- If multiple interpretations exist, present them - don't pick silently.
|
|
|
- If a simpler approach exists, say so. Push back when warranted.
|
|
|
- If something is unclear, stop. Name what's confusing. Ask.
|
|
|
|
|
|
## 2. Simplicity First
|
|
|
|
|
|
**Minimum code that solves the problem. Nothing speculative.**
|
|
|
|
|
|
- No features beyond what was asked.
|
|
|
- No abstractions for single-use code.
|
|
|
- No "flexibility" or "configurability" that wasn't requested.
|
|
|
- No error handling for impossible scenarios.
|
|
|
- If you write 200 lines and it could be 50, rewrite it.
|
|
|
|
|
|
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
|
|
|
|
|
## 3. Surgical Changes
|
|
|
|
|
|
**Touch only what you must. Clean up only your own mess.**
|
|
|
|
|
|
When editing existing code:
|
|
|
- Don't "improve" adjacent code, comments, or formatting.
|
|
|
- Don't refactor things that aren't broken.
|
|
|
- Match existing style, even if you'd do it differently.
|
|
|
- If you notice unrelated dead code, mention it - don't delete it.
|
|
|
|
|
|
When your changes create orphans:
|
|
|
- Remove imports/variables/functions that YOUR changes made unused.
|
|
|
- Don't remove pre-existing dead code unless asked.
|
|
|
|
|
|
The test: Every changed line should trace directly to the user's request.
|
|
|
|
|
|
## 4. Goal-Driven Execution
|
|
|
|
|
|
**Define success criteria. Loop until verified.**
|
|
|
|
|
|
Transform tasks into verifiable goals:
|
|
|
- "Add validation" → "Write tests for invalid inputs, then make them pass"
|
|
|
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
|
|
- "Refactor X" → "Ensure tests pass before and after"
|
|
|
|
|
|
For multi-step tasks, state a brief plan:
|
|
|
```
|
|
|
1. [Step] → verify: [check]
|
|
|
2. [Step] → verify: [check]
|
|
|
3. [Step] → verify: [check]
|
|
|
```
|
|
|
|
|
|
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
|
|
|
|
|
---
|
|
|
|
|
|
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
|
