@antadesign/anta 0.3.18 → 0.3.20

package/docs/packages/stickers.md

@@ -0,0 +1,187 @@
+# Stickers
+
+Square illustrated stickers in two flavors per name — a lightweight
+static SVG and a Lottie-driven animated version. Stickers ship in their
+own package, `@antadesign/stickers` (a companion to `@antadesign/anta`,
+kept separate so apps that don't use stickers never install
+`lottie-web`). Each one is its own named export, so the consumer's
+bundler ships only the stickers actually used. The static variant is
+the default; reach for the animated one explicitly when you want
+motion.
+
+```sh
+npm install @antadesign/stickers   # pulls @antadesign/anta + lottie-web
+```
+
+> Both flavors are JSX wrappers over two custom elements,
+> `<a-sticker>` and `<a-sticker-animated>`, registered by
+> `@antadesign/stickers/elements`. Plain HTML/JS consumers can drive the
+> elements directly via `setAttribute` instead of using the JSX
+> wrappers — see *Non-React consumers* below.
+
+The full set is also published as a [Telegram sticker pack](https://t.me/addstickers/SnoutyAntithesis).
+
+## Props
+
+Both flavors share the same base props; the animated flavor adds playback props.
+
+### `Sticker{Name}` (static)
+
+| Prop | Type | Description |
+|---|---|---|
+| `size?` | `number` | Edge length in pixels. Stickers are always square. Defaults to `256`. |
+| `label?` | `string` | Accessible name. When set, the sticker is exposed as `role="img"` + `aria-label`. Omitted ⇒ `aria-hidden="true"` (decorative). |
+
+Inherited props (`className`, `style`).
+
+### `Sticker{Name}Animated` (Lottie)
+
+Same as the static base, plus:
+
+| Prop | Type | Description |
+|---|---|---|
+| `paused?` | `boolean \| number` | `true` freezes at the current frame; a number freezes at that time in seconds. Omit (or pass `false`) to play. |
+| `delay?` | `number` | Seconds to wait at the first frame before playing. |
+| `playOnce?` | `boolean` | Plays once and holds the final frame instead of looping. |
+| `replayOnClick?` | `boolean` | With `playOnce`, lets people click or press Enter/Space to replay the animation. The sticker becomes a labeled button. |
+
+Use the web component directly when you are not using React or Preact and a native control does not fit.
+
+Pass the generated SVG payload to `<a-sticker>` and set a size through
+`--sticker-size`. The animated element takes its generated Lottie JSON through
+`animation` instead.
+
+```html
+<a-sticker
+  role="img"
+  aria-label="Purple circle"
+  svg='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><circle cx="8" cy="8" r="7" fill="currentColor"/></svg>'
+  style="--sticker-size: 96px; color: var(--text-1-brand)"
+></a-sticker>
+```
+
+## Sizing
+
+Pass `size` (a number, in pixels) to control width and height together.
+Default is `256`. Stickers are always square.
+
+```tsx
+<StickerVacation />                    // 256×256
+<StickerVacation size={128} />         // 128×128
+<StickerVacationAnimated size={64} />  // 64×64
+```
+
+Internally, `size` is applied as the `--sticker-size` CSS custom
+property on the rendered `<a-sticker>` / `<a-sticker-animated>`. The
+base CSS rule reads it as
+`width: var(--sticker-size, 256px); height: var(--sticker-size, 256px)`.
+That means consumer CSS (or a parent's variable cascade) can drive
+sticker size too:
+
+```css
+.sticker-grid { --sticker-size: 96px; }
+```
+
+## Animation control
+
+`paused`, `delay`, `playOnce`, and `replayOnClick` only apply to
+`Sticker{Name}Animated`.
+They map to observed element attributes:
+
+```tsx
+<StickerCodingAnimated />                  // autoplay, looping
+<StickerCodingAnimated paused />           // freeze at the current frame
+<StickerCodingAnimated paused={1.5} />     // freeze at 1.5 seconds
+<StickerCodingAnimated paused={false} />   // explicitly play (same as omitted)
+<StickerCodingAnimated delay={0.5} />      // wait half a second, then play
+<StickerCodingAnimated playOnce />         // play once, then hold the final frame
+<StickerCodingAnimated playOnce replayOnClick label="Replay coding sticker" />
+```
+
+## Adding your own stickers
+
+`@antadesign/stickers` ships a generator script at
+`@antadesign/stickers/generate-stickers.mjs`. Drop your sources in a
+folder structured the same way as the built-in set — one subfolder per
+sticker, with a `<name>.json` (Lottie) and/or `<name>.svg` (static
+pose):
+
+```
+my-stickers/
+  happy/
+    happy.json
+    happy.svg
+  sad/
+    sad.json
+```
+
+Then point the generator at it:
+
+```sh
+node ./node_modules/@antadesign/stickers/dist/generate-stickers.mjs \
+  --input ./my-stickers \
+  --output ./src/my-generated-stickers
+```
+
+The emitted modules import their `Sticker` / `StickerAnimated` runtime
+wrappers from `@antadesign/stickers` by default; pass `--package <name>`
+to point them at a different specifier (e.g. your own re-export).
+
+Out comes one `<name>.ts` per static sticker and one `<name>-animated.ts`
+per animated sticker, plus an `index.ts` barrel. Import and use:
+
+```ts
+import { StickerHappy, StickerSadAnimated } from './my-generated-stickers'
+
+<StickerHappy size={96} />
+<StickerSadAnimated paused={1.5} />
+```
+
+### Source conventions
+
+- Animated stickers are `<name>.json` Lottie payloads.
+- Either file is optional — supply just the SVG for a static-only
+  sticker, just the JSON for an animated-only one, or both.
+
+### Conflicting names
+
+If a generated sticker has the same name as one of the pack's built-ins
+(e.g. `vacation`), the generator prints a warning. The built-in sticker
+imported from `@antadesign/stickers` is unaffected — your generated
+barrel exposes yours under your own import path.
+
+## Non-React consumers
+
+The custom elements `<a-sticker>` and `<a-sticker-animated>` are
+framework-agnostic. Each generated module exports the raw payload
+(`svg` string for static, `animationJson` string for animated)
+alongside the JSX component, so non-React consumers can pull just the
+data and drive the elements directly:
+
+```js
+import { svg } from '@antadesign/stickers/vacation'
+import { animationJson } from '@antadesign/stickers/vacation-animated'
+
+const still = document.createElement('a-sticker')
+still.setAttribute('svg', svg)
+still.style.setProperty('--sticker-size', '128px')
+document.body.appendChild(still)
+
+const movie = document.createElement('a-sticker-animated')
+movie.setAttribute('animation', animationJson)
+document.body.appendChild(movie)
+```
+
+The static element renders the SVG into its own shadow DOM; the
+animated element drives a shadow-DOM `<svg>` via `lottie-web`. Both
+consume their payload through the `svg` / `animation` HTML attribute —
+the JSX wrapper passes the same data, just through React/Preact's
+prop layer.
+
+## SSR
+
+`@antadesign/stickers/elements` references browser APIs (`HTMLElement`,
+`customElements`, `lottie-web`). In SSR contexts (Astro, Next.js) gate
+the import behind a client boundary — same rule as anta's own elements.
+The sticker components themselves render fine on the server (just JSX);
+only the underlying custom-element classes need the browser.

package/docs/packages/table.md

@@ -0,0 +1,153 @@
+# Table
+
+A tabular layout for structured data — rows, columns, headers, sorting,
+selection. **Not yet shipped in `@antadesign/anta`.** For now, use the
+component published in the Anta Figma library; the React/web-component
+implementation will follow.
+
+## Status
+
+Available in Figma; not yet implemented in code. There is no
+`<Table>` component or `<a-table>` element to import. This page will
+grow Props / Examples / Tokens sections once the component lands.
+
+## Figma source
+
+The Table component lives in the **Anta 0.2** Figma library:
+
+[Open Table in Figma →](https://www.figma.com/design/cIvfEHHCYgJb5RYuMqBMbN/Anta-0.2?node-id=882-18882&t=98Cj3I7mvzMVVchU-11)
+
+## Preview
+
+## Plain HTML tables
+
+While the `<Table>` component is in design, Anta's `reset.css` ships a
+polite baseline for the native `<table>` element so plain HTML tables
+look intentional out of the box. The defaults are deliberately minimal:
+top-left aligned cells with 5 × 10 px padding, hairline row separators
+in `--border-4`, semibold `<thead>` cells, and no outer frame or
+column dividers. Set `font-variant-numeric: tabular-nums` so numeric
+columns line up.
+
+All rules live inside `@layer anta`, so any consumer rule outside a
+layer (or in `components` / `utilities`) overrides without specificity
+fights or `!important`.
+
+### Default
+
+
+
+      Token
+      Value
+      Usage
+
+
+
+
+      --text-1
+      #1c1f23
+      Primary body copy
+
+
+      --text-3
+      #52575e
+      Secondary labels, sidebar links
+
+
+      --border-5
+      #e8eaed
+      Hairline dividers, table row separators
+
+
+
+```html
+<table>
+  <thead>
+    <tr><th>Token</th><th>Value</th><th>Usage</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>--text-1</td><td>#1c1f23</td><td>Primary body copy</td></tr>
+    …
+  </tbody>
+</table>
+```
+
+### Bordered
+
+Add `data-bordered` to draw the outer frame, vertical column dividers,
+and 3 px rounded corners. Under the hood the variant switches to
+`border-collapse: separate` because `border-radius` doesn't render
+reliably with collapsed borders.
+
+
+
+      Token
+      Value
+      Usage
+
+
+
+
+      --text-1
+      #1c1f23
+      Primary body copy
+
+
+      --text-3
+      #52575e
+      Secondary labels, sidebar links
+
+
+      --border-5
+      #e8eaed
+      Hairline dividers, table row separators
+
+
+
+```html
+<table data-bordered>
+  …
+</table>
+```
+
+### With a caption
+
+`<caption>` is the semantic title for a data table — the first child of
+`<table>`, announced by screen readers as the table's accessible name.
+Browsers render it as a block above the rows; Anta's only opinion is
+left alignment (browser default is centered).
+
+  Color tokens used by the docs sidebar
+
+
+      Token
+      Role
+
+
+
+
+      --text-1-brand
+      Logo wordmark
+
+
+      --text-3
+      Nav link, idle state
+
+
+      --text-1
+      Nav link, current page
+
+
+
+```html
+<table data-bordered>
+  <caption>Color tokens used by the docs sidebar</caption>
+  <thead>
+    <tr><th>Token</th><th>Role</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>--text-1-brand</td><td>Logo wordmark</td></tr>
+    …
+  </tbody>
+</table>
+```

package/docs/theming.md

@@ -0,0 +1,13 @@
+# Theming
+
+Anta's palette is generative. Every color in the system derives from six tone seeds (`--anta-seed-neutral`, `--anta-seed-brand`, `--anta-seed-info`, …), and a seed contributes only its hue: the lightness and chroma of every background, text, border, and component state come from Anta's formulas, tuned per role and per theme. Reskinning a tone is one custom property, and the whole scale re-derives in both light and dark:
+
+```css
+:root {
+  --anta-seed-brand: #0f766e; /* a teal brand; every brand token follows */
+}
+```
+
+Past the seeds, any look and feel is reachable. Anta's styles live in `@layer anta`, so an un-layered rule you write wins without `!important`, and shadow-DOM components expose `::part(...)` hooks. Per component, the `tone` prop takes a named tone or any CSS color and derives that component's full rest/hover/active curve from it. Each component page lists its own hooks under Styling.
+
+The lab below shows the derivation live. For each toned component, the shipped Default sits next to a Custom preview driven by the seed picker, with the formula constants editable and the resolved CSS shown.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@antadesign/anta",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "NOTICES.md"
   ],
   "packageManager": "pnpm@8.13.1",
@@ -44,20 +45,23 @@
     }
   },
   "scripts": {
-    "build": "pnpm run build:js && pnpm run build:css && pnpm run build:types",
+    "build": "pnpm run build:js && pnpm run build:css && pnpm run build:types && pnpm run build:docs",
     "build:dev": "pnpm run build:js && pnpm run build:css:dev && pnpm run build:types",
-    "build:css": "esbuild $(find src -name '*.css') --minify --loader:.module.css=css --outdir=dist --outbase=src && cp scripts/generate-icons.mjs dist/",
+    "build:css": "esbuild $(find src -name '*.css') --minify --outdir=dist --outbase=src && cp scripts/generate-icons.mjs dist/",
     "build:css:dev": "find src -name '*.css' | while IFS= read -r f; do d=\"dist/${f#src/}\"; mkdir -p \"$(dirname \"$d\")\"; cp \"$f\" \"$d\"; done && cp scripts/generate-icons.mjs dist/",
-    "build:js": "esbuild $(find src \\( -name '*.ts' -o -name '*.tsx' \\) ! -name '*.d.ts') --outdir=dist --outbase=src --jsx=automatic --jsx-import-source=@antadesign/anta --format=esm --target=ES2022 --loader:.module.css=local-css --loader:.css=global-css",
+    "build:js": "esbuild $(find src \\( -name '*.ts' -o -name '*.tsx' \\) ! -name '*.d.ts') --outdir=dist --outbase=src --jsx=automatic --jsx-import-source=@antadesign/anta --format=esm --target=ES2022 --loader:.css=global-css",
     "build:types": "tsc -p src/tsconfig.json",
-    "dev": "echo $$ > .dev.pid; trap 'rm -f .dev.pid' EXIT; pnpm run build:dev && pnpm --filter @antadesign/stickers run build:dev && pnpm --filter anta-site run docs && (node scripts/dev-watch.mjs & pnpm --filter anta-site run dev:server & wait)",
+    "build:docs": "pnpm --filter anta-site run docs:api && pnpm --filter anta-site run docs:pages && node scripts/generate-package-docs.mjs",
+    "dev": "node scripts/dev.mjs",
+    "dev:run": "echo $$ > \"$ANTA_DEV_PID_FILE\"; trap 'rm -f \"$ANTA_DEV_PID_FILE\"' EXIT; pnpm run build:dev && pnpm --filter @antadesign/stickers run build:dev && pnpm --filter anta-site run docs && (node scripts/dev-watch.mjs & pnpm --filter anta-site run dev:server & wait)",
     "stop": "node scripts/dev-stop.mjs",
     "typecheck": "tsc --noEmit -p src/tsconfig.json",
     "lint": "node scripts/lint-getters.mjs",
     "icons": "node scripts/generate-icons.mjs --input src/elements/icons --output src/elements --name a-icon.shapes --internal",
     "clean": "rm -rf dist",
     "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "prepack": "pnpm run build:docs"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",