@usableapp/cardds 0.3.0 → 0.4.0

package/dist/type/Icon.d.ts

@@ -1,16 +1,31 @@
-import { type IconName } from './icons.js';
-export type { IconName };
-export interface IconProps extends Omit<React.ComponentPropsWithoutRef<'svg'>, 'children'> {
-    /** one of the 57 Lucide symbols in icons.svg (arrow-left, bell, check, chevron-down, id-card, plus, x, …) */
-    name: IconName;
+import type { ReactNode } from 'react';
+import { type IconName as StockIconName } from './icons.js';
+/** an icon's name: one of the stock symbols (autocompleted) — or any name a project registered with `registerIcons` */
+export type IconName = StockIconName | (string & {});
+/**
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export declare function registerIcons(icons: Record<string, string | {
+    body: string;
+    attrs?: Record<string, string>;
+}>): void;
+export interface IconProps extends Omit<React.ComponentProps<'svg'>, 'children' | 'name'> {
+    /** a stock symbol (arrow-left, bell, check, chevron-down, id-card, plus, x, …) or a name the project registered (`registerIcons`). Omit it to draw with `children`. */
+    name?: IconName;
+    /** a ONE-OFF drawing: the svg's own children (`<path d="…" />`), on a 24×24 box with the shared stroke — for an icon not worth registering */
+    children?: ReactNode;
     /** xs = 16px, inside captions, chips and links · sm = in a small icon button or a field (28px today — one size everywhere, tokens.css) · md (default) = the 28px icon · lg = 32px, empty states */
     size?: 'xs' | 'sm' | 'md' | 'lg';
     /** an accessible name makes the icon meaningful (role="img"); without one it is decorative and hidden from assistive tech */
     label?: string;
 }
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export declare function Icon({ name, size, label, className, ...rest }: IconProps): import("react").JSX.Element;
+export declare function Icon({ name, children, size, label, className, ...rest }: IconProps): import("react").JSX.Element;

package/dist/type/Icon.js

@@ -1,12 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { ICONS } from './icons.js';
+/* the stroke style every stock symbol shares (Lucide): a project's drawing takes it unless it brings its own attrs */
+const STROKE = { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2', strokeLinecap: 'round', strokeLinejoin: 'round' };
+const OWN = new Map();
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export function registerIcons(icons) {
+    for (const [name, d] of Object.entries(icons))
+        OWN.set(name, typeof d === 'string' ? { attrs: STROKE, body: d } : { attrs: { ...STROKE, ...d.attrs }, body: d.body });
+}
+const warned = new Set();
+/**
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export function Icon({ name, size = 'md', label, className, ...rest }) {
-    const icon = ICONS[name];
-    return (_jsx("svg", { ...icon.attrs, className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, "aria-label": label, "aria-hidden": label ? undefined : true, dangerouslySetInnerHTML: { __html: icon.body }, ...rest }));
+export function Icon({ name, children, size = 'md', label, className, ...rest }) {
+    const icon = name === undefined ? undefined : OWN.get(name) ?? ICONS[name];
+    if (name !== undefined && !icon && !warned.has(name)) {
+        warned.add(name);
+        console.warn(`cardds Icon: no icon named "${name}" — a stock name is misspelt, or the project has not registered it (registerIcons)`);
+    }
+    const shared = { className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, 'aria-label': label, 'aria-hidden': label ? undefined : true };
+    // an unknown name draws nothing but keeps its box — a missing icon never takes a screen down
+    if (!icon)
+        return _jsx("svg", { ...STROKE, ...shared, ...rest, children: children });
+    return _jsx("svg", { ...icon.attrs, ...shared, dangerouslySetInnerHTML: { __html: icon.body }, ...rest });
 }

package/dist/type/Text.d.ts

@@ -1,5 +1,7 @@
 export type TextLevel = 'display' | 'h1' | 'h2' | 'title' | 'body' | 'label' | 'caption' | 'overline' | 'stat';
 export interface TextProps extends React.HTMLAttributes<HTMLElement> {
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     /** the type level: display (hero words) · h1 · h2 (a card's heading) · title · body · label · caption · overline (small caps above a heading) · stat (a big number) */
     level: TextLevel;
     /** stat only: the one giant number on a sheet (`.t-stat--xl`) */
@@ -8,6 +10,8 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
     mono?: boolean;
     /** muted ink — follows the card it sits in */
     muted?: boolean;
+    /** takes the remaining room of a row (a heading beside a chip in a flex head) */
+    grow?: boolean;
     /** uppercase */
     caps?: boolean;
     /** the element; defaults per level (h2 for display/h1/h2, p for title/body/stat, span for the rest) */
@@ -18,7 +22,9 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
  * Headings inside a card head are h2 by default; a screen title in a TopBar is h1.
  * Everything scales from the root font-size, so there are no pixel sizes to pick.
  */
-export declare function Text({ level, xl, mono, muted, caps, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+export declare function Text({ level, xl, mono, muted, caps, grow, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     defaultChecked?: boolean | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined;

package/dist/type/Text.js

@@ -8,9 +8,9 @@ const DEFAULT_AS = {
  * Headings inside a card head are h2 by default; a screen title in a TopBar is h1.
  * Everything scales from the root font-size, so there are no pixel sizes to pick.
  */
-export function Text({ level, xl, mono, muted, caps, as, className, ...rest }) {
+export function Text({ level, xl, mono, muted, caps, grow, as, className, ...rest }) {
     return createElement(as ?? DEFAULT_AS[level] ?? 'span', {
-        className: cx(`t-${level}`, level === 'stat' && xl && 't-stat--xl', level === 'stat' && mono && 't-stat--mono', muted && 't-muted', caps && 't-caps', className),
+        className: cx(`t-${level}`, level === 'stat' && xl && 't-stat--xl', level === 'stat' && mono && 't-stat--mono', muted && 't-muted', caps && 't-caps', grow && 'grow', className),
         ...rest,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",
@@ -13,7 +13,8 @@
     "build": "node scripts/build-icons.mjs && tsc -p tsconfig.json && node scripts/flatten-css.mjs",
     "test": "playwright test",
     "validate:inbox": "node scripts/validate-inbox.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "knobs": "node scripts/knobs.mjs"
   },
   "devDependencies": {
     "@playwright/test": "1.58.2",