@inkorange/space-ui 1.10.0 → 1.12.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md
+
+Instructions for AI coding agents. Two audiences, in order: writing an
+application that uses SpaceUI, then working inside this repository.
+
+The complete, generated API reference lives at
+<https://space-components.vercel.app/llms.txt> (and `llms-full.txt` for every
+prop, data shape and token). It is derived from this source on every deploy, so
+it describes the published version exactly. Prefer it over anything you
+remember about this library.
+
+---
+
+## Using SpaceUI in an application
+
+```bash
+npm install @inkorange/space-ui
+```
+
+```tsx
+import "@inkorange/space-ui/styles.css";
+import { Card, Heading, Text, Button } from "@inkorange/space-ui";
+```
+
+Three entry points, and no others: the package itself, `./styles.css` (the one
+required stylesheet) and `./tokens.css` (the token layer alone, for a project
+that wants the palette and the scales without the components).
+
+1. **Import the stylesheet once, at the application root.** All component CSS
+   ships precompiled in one file. There is no per-component import, and no Sass
+   for consumers.
+2. **Do not add a provider, context or theme wrapper.** Components read tokens
+   straight from CSS custom properties on the document.
+3. **The library is dark-only, by design.** The tokens can be re-pointed, but
+   the components are drawn as lit glass over a dark ground, so a light
+   palette misrepresents every surface. There is no supported light theme; do
+   not build one.
+4. **Style with tokens, never raw lengths or colours.** `var(--spacing-md)`,
+   not `16px`. Spacing is an 8pt grid — every step is a multiple of
+   `--sp-grid-base-size`. Control heights come from `--sp-control-height`
+   (40px, with `-sm` 36 and `-lg` 48), so a Button and the Select beside it
+   match. Colour is a named role: `primary` for emphasis, `success`,
+   `warning`, `danger` and `accent` for status, with `-solid`, `-text`,
+   `-soft`, `-border`, `-glow` and `-deep` saying which job within the role.
+5. **Override a component token on a class, not with an inline style.** An
+   inline style wins over every media and container query the consumer will
+   later write.
+
+   ```css
+   .featured { --sp-carousel-view-count: 2.5; }
+   ```
+6. **Boolean props default to false**, so `<Button fullWidth />` is the idiom,
+   not `fullWidth={true}`. The one exception is `animated`, which defaults to
+   true.
+7. **Selection components are controlled through `onValueChange`** — Select,
+   Slider, RadioGroup, CheckboxGroup, Tabs. Native text inputs (TextField,
+   TextArea) keep React's own `value` and `onChange`.
+8. **Keyboard support and ARIA are already inside each component.** Roving
+   tabindex, arrow-key navigation, Escape handling, `aria-checked`,
+   `aria-expanded` and `aria-current` are implemented; do not re-declare them
+   from outside. Do pass `aria-label` where a control has no visible label.
+9. **Nothing touches the DOM at import time.** Components that measure do it in
+   effects, so the entry point imports cleanly in a server build. Components
+   needing the top layer use the platform popover API, so no portal target has
+   to be provided.
+
+Peer dependencies are `react >= 19` and `react-dom >= 19`. There are no other
+runtime dependencies.
+
+---
+
+## Working in this repository
+
+A pnpm monorepo: the library in `packages/space-ui`, a Ladle gallery in
+`apps/docs`.
+
+```
+pnpm test        # vitest: a happy-dom unit project and a real-Chromium browser project
+pnpm build       # build the library
+pnpm docs        # the gallery at localhost:61000
+pnpm changeset   # required for any change under packages/space-ui/src
+```
+
+- **Styling a component follows a fixed pattern**, documented in
+  [CLAUDE.md](CLAUDE.md) and as a skill in
+  `.claude/skills/space-ui-styling/`. Read one of them before writing a
+  `*.module.scss`. The short version: spacing names a step, type is `rem()`
+  written in px, control heights come from the ladder, colour is a token, and
+  the only exceptions are hairlines and optical nudges — which go in the
+  `EXCEPTIONS` map in `src/components/grid.test.ts` with a reason.
+- **Several invariants are tests, not conventions**, and they fail CI rather
+  than review: the spacing grid and rem type (`grid.test.ts`), the token
+  surface (`tokens.test.ts`), the ban on the component library this one
+  replaced, and the documentation a component publishes
+  (`published-docs.test.ts` — every component needs a description, and no doc
+  comment may name anything internal, because doc comments ship in the `.d.ts`
+  and in `llms.txt`).
+- **A component's JSDoc is public copy.** It is published into the shipped
+  types, the gallery's prop tables, and the generated agent documentation.
+  Write it for someone who installed this from npm: what the component is,
+  when to reach for it, and what to use instead when it is the wrong choice.
+- **Every PR touching `packages/space-ui/src` needs a changeset.** CI enforces
+  it. Prefer a minor bump over a major one.
+- **Visual changes wait for the owner's sign-off in the gallery** before being
+  committed.
+- **Commits are authored solely by Chris West.** Never add `Co-Authored-By` or
+  any AI-attribution trailer.
+- Agent-facing files — `llms.txt`, `llms-full.txt`, `reference.html`,
+  `robots.txt`, `sitemap.xml` — are generated at docs build time by
+  `apps/docs/vite-plugin-agent-docs.ts` from the same TypeScript AST pass that
+  builds the gallery's prop tables. Never hand-write them, and never commit
+  them: they are build output, and a committed copy goes stale.

package/README.md

@@ -205,6 +205,40 @@ their edge cases already found rather than imagined.
 **Requires** React 19 and a dark surface. There is deliberately no light theme;
 these components assume the dark they were drawn for.
 
+## For AI agents
+
+The full API — every component, prop, data shape and design token — is
+published in machine-readable form, generated from this source on every deploy
+so it describes the published version exactly:
+
+- [`llms.txt`](https://space-components.vercel.app/llms.txt) — the index:
+  install, the rules below, the scales, and one line per component.
+- [`llms-full.txt`](https://space-components.vercel.app/llms-full.txt) — the
+  whole reference, as one file.
+- [`reference.html`](https://space-components.vercel.app/reference.html) — the
+  same, as a page that needs no JavaScript.
+- [`AGENTS.md`](https://github.com/inkorange/space-ui/blob/main/AGENTS.md) —
+  the short version, and it ships inside the package, so an agent working in a
+  project that depends on SpaceUI finds it without fetching anything.
+
+The things that are easy to get wrong because no type signature says them:
+
+- **One stylesheet import, at the root.** No per-component CSS, no provider, no
+  context, no theme wrapper, no build plugin.
+- **Dark only.** The tokens can be re-pointed, but there is no supported light
+  theme — these components are drawn as lit glass over a dark ground.
+- **Tokens, not lengths.** `var(--spacing-md)` over `16px`; spacing is an 8pt
+  grid and control heights come from a three-step ladder, so controls placed
+  side by side line up without arithmetic.
+- **Set a component token on a class, never in an inline `style`** — inline
+  beats every media query a consumer will write afterwards.
+- **Booleans default to false**, so `<Button fullWidth />` is the idiom.
+  `animated` is the one exception, defaulting to true.
+- **Selection is controlled through `onValueChange`.** Native text inputs keep
+  React's `value` and `onChange`.
+- **Keyboard behaviour and ARIA are already inside the components.** Add
+  `aria-label` where there is no visible label; do not re-declare the rest.
+
 ## License
 
 MIT

package/dist/components/Autocomplete.d.ts

@@ -59,4 +59,15 @@ export interface AutocompleteProps extends Omit<React.InputHTMLAttributes<HTMLIn
     /** Applied to the wrapper — set width here. */
     style?: React.CSSProperties;
 }
+/**
+ * A text field that offers matching rows as you type.
+ *
+ * It holds no data of its own. Give it `options` and it renders them,
+ * highlights one, moves that highlight with the arrow keys, and calls
+ * `onSelect` when a row is chosen — however those options were produced.
+ *
+ * The list is a popover rather than a block in the flow: results that appear
+ * mid-keystroke and push the page down under the cursor are disorienting, and
+ * whatever is being searched usually sits directly below the field.
+ */
 export declare function Autocomplete({ value, onValueChange, options, onSelect, icon, caseSensitive, preFiltered, loading, loadingMessage, emptyMessage, footer, animated, className, style, ...inputProps }: AutocompleteProps): React.JSX.Element;

package/dist/components/Badge.d.ts

@@ -24,9 +24,9 @@ export interface BadgeProps extends SpacingProps, Omit<React.HTMLAttributes<HTML
     variant?: "soft" | "solid";
     /** 1 is the default chip; 2 is for standalone use away from body text. */
     size?: "1" | "2";
-    /** Badges are single-line by default (Radix parity). Long free-text
-     *  content — e.g. user-named star systems on planet cards — opts into
-     *  wrapping so it can't overflow its card. */
+    /** Badges are single-line by default: one that wraps stops reading as a
+     *  badge. Opt into wrapping for free text you do not control — anything a
+     *  reader named rather than you — so it cannot overflow what contains it. */
     wrap?: boolean;
     /** Label text. Keep it short — a badge that wraps stops reading as one. */
     children?: ReactNode;

package/dist/components/Button.d.ts

@@ -13,8 +13,12 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
     animated?: boolean;
 }
 /**
- * "Limb-lit glass" button: cosmic glass capsule whose rim glows like a planet's
- * sunlit atmosphere limb, with twinkling stars inside and a periodic glint
- * sweep. Plain <button>, so it composes with Radix Dialog.Trigger (Slot).
+ * The thing a reader presses to make something happen. A glass capsule whose
+ * rim glows like a planet's sunlit limb, with stars twinkling inside it and a
+ * glint that sweeps across it now and then.
+ *
+ * It renders a plain `<button>` and forwards its ref, so it drops into
+ * anything that needs to borrow a trigger — a dialog, a menu, a router link's
+ * render prop — without a wrapper in between.
  */
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/Dialog.d.ts

@@ -72,6 +72,22 @@ export declare function Title({ className, ...rest }: HeadingProps): React.JSX.E
  * description. Optional, and only announced when present.
  */
 export declare function Description(props: TextProps): React.JSX.Element;
+/**
+ * A modal window over the page, for a task that has to finish or be abandoned
+ * before anything else happens.
+ *
+ * It rides the platform's own `<dialog>`, so the backdrop, the top layer, the
+ * Escape key and the focus trap are the browser's rather than an
+ * approximation of them. Opening moves focus inside; closing returns it to
+ * whatever opened it.
+ *
+ * For a decision with consequences — deleting, discarding, overwriting —
+ * reach for `AlertDialog`, which refuses to close by a click outside, so a
+ * misplaced click cannot answer the question for the reader.
+ *
+ * Compose it from the parts hanging off this name: `Dialog.Trigger`,
+ * `Dialog.Content`, `Dialog.Title`, `Dialog.Description` and `Dialog.Close`.
+ */
 export declare const Dialog: (({ open, onOpenChange, children }: DialogProps) => React.JSX.Element) & {
     Trigger: typeof Trigger;
     Close: typeof Close;

package/dist/components/DropdownMenu.d.ts

@@ -56,6 +56,22 @@ declare function Item({ asChild, color, onSelect, children }: DropdownMenuItemPr
  * routine ones, so the two are not adjacent to a moving cursor.
  */
 declare function Separator(): React.JSX.Element;
+/**
+ * A button that opens a list of actions.
+ *
+ * Actions, not choices: every item does something when picked, and nothing in
+ * the menu holds a value. For choosing one of a set of values, that is
+ * `Select`, which looks similar and means something entirely different to a
+ * screen reader.
+ *
+ * Arrow keys move through the items, Home and End jump to the ends, Escape
+ * closes and returns focus to the button, and typing a letter jumps to the
+ * next item starting with it. The panel uses the browser's popover layer, so
+ * it stacks above the page without a z-index to maintain.
+ *
+ * Compose it from `DropdownMenu.Item`, `DropdownMenu.Label` and
+ * `DropdownMenu.Separator`.
+ */
 export declare const DropdownMenu: typeof DropdownMenuRoot & {
     Item: typeof Item;
     Separator: typeof Separator;

package/dist/components/IconToggle.d.ts

@@ -6,13 +6,15 @@ export interface IconToggleOption<V extends string> {
     label: string;
 }
 /**
- * A segmented icon toggle: every option is always visible in one pill, the
- * selected one reads as active, clicking any option selects it. Built for the
- * scene view switcher (planet / orrery / surface), where the old pattern —
- * showing only the views you are NOT on and swapping icons on click — made
- * the control's meaning flip under the cursor (owner: both icons should be
- * "always visible, the selected one is the active one"). Generic over the
- * option set so other icon-mode switchers can reuse it.
+ * A segmented icon toggle: every option visible at once in a single pill, the
+ * selected one reading as active, and a click on any of them selecting it.
+ *
+ * Reach for it to switch between modes or views of the same thing, where the
+ * options are few and each has an obvious glyph. The alternative pattern — one
+ * button that shows the mode you are NOT in and swaps its own icon on click —
+ * is deliberately not what this does: the control's meaning changes under the
+ * cursor, and nobody can tell whether the icon means "you are here" or "go
+ * here". Generic over the option set, so the values stay your own union type.
  */
 export declare function IconToggle<V extends string>({ options, value, onValueChange, orientation, className, }: {
     /** The segments, in display order. Every option is always visible —

package/dist/components/Loader.d.ts

@@ -7,9 +7,13 @@ export interface LoaderProps {
     className?: string;
 }
 /**
- * Orbital spinner: a small pulsing "planet" disc at the center of a static
- * ring, with a "moon" dot traveling the ring. Dependency-free CSS animation
- * so it composes cleanly wherever a lazy chunk or async panel needs a
- * space-themed loading state (see SurfaceView's dynamic-import loader).
+ * An orbital spinner, for work whose length you cannot measure: a small
+ * pulsing planet at the centre of a static ring, with a moon travelling it.
+ * Where you CAN measure the work, use `Progress` instead — a spinner that
+ * could have been a bar tells the reader less than it knows.
+ *
+ * The motion is pure CSS and runs on the compositor, so it keeps turning
+ * smoothly while the main thread is busy doing the thing it is waiting on —
+ * which is exactly when a loader is on screen.
  */
 export declare function Loader({ size, label, className }: LoaderProps): import("react").JSX.Element;

package/dist/components/RadioGroup.d.ts

@@ -34,6 +34,21 @@ export interface RadioGroupItemProps {
  * nesting one label inside another is invalid HTML.
  */
 declare function Item({ value, disabled, children }: RadioGroupItemProps): React.JSX.Element;
+/**
+ * Exactly one choice from a set you can see all of at once.
+ *
+ * Use it where the options matter enough to be read side by side and there are
+ * few enough to show — up to about seven. Past that a `Select` keeps the page
+ * calm. Where several answers can be true at the same time, that is
+ * `CheckboxGroup`.
+ *
+ * Hold the chosen value and pass `onValueChange`. Each orb ignites when it is
+ * chosen, arrow keys move between the options the way a native radio group
+ * does, and a label that wraps to two lines keeps its orb beside the first
+ * line rather than drifting to the middle.
+ *
+ * Compose it from `RadioGroup.Item`.
+ */
 export declare const RadioGroup: typeof RadioGroupRoot & {
     Item: typeof Item;
 };

package/dist/components/Select.d.ts

@@ -47,6 +47,23 @@ export interface SelectItemProps {
  * selected, so anything rendered here has to read correctly in both places.
  */
 declare function Item({ value, disabled, children }: SelectItemProps): React.JSX.Element;
+/**
+ * Choosing one value from a list, with the list kept out of the way until it
+ * is wanted.
+ *
+ * The right control when the options are many, or dull, or both — a country, a
+ * size, a sort order. Where there are few options and each one deserves to be
+ * read, `RadioGroup` shows them all without a click. Where the items are
+ * actions rather than values, that is `DropdownMenu`.
+ *
+ * The panel opens on the browser's popover layer, which is what lets it escape
+ * a dialog, a transformed ancestor or a clipping overflow and sit above the
+ * page at its full height. It flips above the trigger when there is no room
+ * below, follows the trigger if the page scrolls, and closes on Escape with
+ * focus handed back. Typing jumps to a matching option.
+ *
+ * Compose it from `Select.Item`.
+ */
 export declare const Select: typeof SelectRoot & {
     Item: typeof Item;
 };

package/dist/components/Slider.d.ts

@@ -46,5 +46,15 @@ export interface SliderProps {
  * With two thumbs they cannot cross: each is clamped to the other, so the
  * array stays in order and a range can never read back inverted. `minDistance`
  * keeps a gap between them where a zero-width range would be meaningless.
+ *
+ * The pointer is the component's own business, and the inputs take none of it.
+ * Two inputs each covering the whole track cannot decide between them which
+ * thumb a press meant: the browser hit-tests before any of this code runs, so
+ * the answer came down to which input was later in the DOM. Whenever the
+ * thumbs were within a thumb's width of each other — constant over a wide
+ * range, where a few units are a fraction of a pixel — a press on the lower
+ * one was handed to the upper one, which then refused to travel. So a press
+ * anywhere on the control is measured here, against where the thumbs actually
+ * are, and the nearest one is dragged until the pointer is released.
  */
 export declare const Slider: React.ForwardRefExoticComponent<SliderProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/Tabs.d.ts

@@ -60,6 +60,21 @@ declare function Content({ value, children, }: {
     /** Panel contents. Unmounted while another tab is selected. */
     children?: ReactNode;
 }): React.JSX.Element | null;
+/**
+ * Several panels sharing one piece of the page, one visible at a time.
+ *
+ * Right for views of the same subject that a reader moves between and
+ * compares — overview, history, settings for one record. Wrong for steps in a
+ * sequence, where the reader needs to know how far along they are, and wrong
+ * for content that should be findable by search or linkable on its own: a
+ * hidden panel is invisible to both.
+ *
+ * Arrow keys move between the tabs, Home and End jump to the ends, and only
+ * the selected tab is in the tab order, so one press of Tab leaves the strip
+ * for the panel instead of walking every tab in it.
+ *
+ * Compose it from `Tabs.List`, `Tabs.Trigger` and `Tabs.Content`.
+ */
 export declare const Tabs: typeof TabsRoot & {
     List: typeof List;
     Trigger: typeof Trigger;

package/dist/components/TextField.d.ts

@@ -20,6 +20,18 @@ declare function Slot({ children, }: {
     /** The slot's contents — an icon, a unit, a short affordance. */
     children?: ReactNode;
 }): React.JSX.Element;
+/**
+ * A single line of text the reader types.
+ *
+ * A real `<input>` underneath, so `value`, `onChange`, `type`, `required`,
+ * `autoComplete` and the rest of the native attributes all work as they
+ * already do, and the browser's own autofill and validation come along with
+ * them. For more than a line, use `TextArea`.
+ *
+ * Put an icon, a unit or a small button beside the text with `TextField.Slot`.
+ * It sits inside the field's rim and keeps its own padding, so the text never
+ * runs underneath it.
+ */
 export declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>> & {
     Slot: typeof Slot;
 };