@trembus/ui 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,17 @@
 # @trembus/ui
 
+[![npm](https://img.shields.io/npm/v/@trembus/ui.svg)](https://www.npmjs.com/package/@trembus/ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/nicholasosto/Trembus-Component-Library/blob/main/LICENSE)
+[![Storybook](https://img.shields.io/badge/Storybook-live-ff4785?logo=storybook&logoColor=white)](https://nicholasosto.github.io/Trembus-Component-Library/)
+
 Trembus React component library — first-principles UX (tokens → primitives →
 components), each component carrying a machine-checked "3 UI jobs" contract
 (Reveal State · Afford Action · Acknowledge Input). claude.ai-clean **light** +
-Trembus **dark** + blood-dark **reliquary** themes.
+Trembus **dark** + blood-dark **reliquary** themes, zero styling config.
+
+**🔭 [Browse every component + theme in the live Storybook →](https://nicholasosto.github.io/Trembus-Component-Library/)**
+
+## Install
 
 ```sh
 pnpm add @trembus/ui react react-dom
@@ -32,11 +40,37 @@ export function App() {
 }
 ```
 
-Primitives (`Box`, `Stack`/`Inline`, `Text`, `Pressable`) compose into the higher
-components; surfaces can wear a **material** skin via `<Box material="glass">`.
+No Tailwind, no build-tool config. Theming is pure CSS custom properties — override
+any `--tcl-*` token to re-skin, or flip `[data-theme]` (`light` · `dark` ·
+`reliquary`). Surfaces can wear a **material** skin via `<Box material="glass">`.
+
+## What's inside
+
+**Primitives** — `Box` (Surface), `Stack` / `Inline` (Relation), `Text` (Mark),
+`Pressable` (Affordance; owns the idle→hover→pressed→focus FSM). Compose these into
+your own components.
+
+**Afford-Action** — `Button`, `IconButton`, `Tabs`, `Menu`.
+
+**Reveal-State** — `Badge`, `Avatar`, `Spinner`, `Skeleton`, `Card`, `Callout`,
+`EmptyState`, `Stat`, `Table`, `Progress`, `Meter`.
+
+**Acknowledge-Input** — `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`,
+`Switch`, `Tooltip`, `Dialog`, `Toast`.
+
+**Visualizations** (Tier-1, data-driven) — `Hub`, `BarChart`, `LineChart`,
+`DonutChart`, `Heatmap`, `Gauge`, `Sparkline`, `Funnel`, `Treemap`, `Timeline`,
+`Swimlane`. (Node-link graphs live in [`@trembus/viz`](https://www.npmjs.com/package/@trembus/viz).)
+
+Hooks (`useAffordanceState`, `useFocusTrap`, `useReturnFocus`, `useReducedMotion`,
+`useDismissable`) and utils (`Portal`, `Slot`, `cx`) are exported too.
+
+## Theming tokens
 
-Browse every component + theme in [Storybook](https://github.com/nicholasosto/Trembus-Component-Library).
+A type-safe `tokens` object (var references) is exported for inline use:
+`style={{ color: tokens.color.accent }}`. The full token vocabulary lives in
+[`@trembus/tokens`](https://www.npmjs.com/package/@trembus/tokens).
 
 ## License
 
-MIT © Nicholas Osto
+MIT © Nicholas Osto · [source & contributing](https://github.com/nicholasosto/Trembus-Component-Library)

package/dist/index.d.ts

@@ -597,6 +597,52 @@ declare type FillBarSize = 'sm' | 'md' | 'lg';
 
 declare type FillBarTone = 'accent' | 'info' | 'success' | 'warning' | 'danger' | 'neutral';
 
+/**
+ * A node in the folder forest. The shape is **nested** (children inline) — the
+ * natural file-tree idiom, and the one that makes lazy loading clean. Ids are
+ * optional: an omitted id is derived from the node's position (`${parentId}/${i}`),
+ * so a literal filesystem dump renders without bookkeeping.
+ */
+export declare interface FolderNode {
+    /** Stable unique id. Omitted → derived from position; provide it if the tree reorders. */
+    id?: string;
+    /** Display name, e.g. "Button.tsx". Doubles as the accessible name. */
+    label: string;
+    /** Folder vs file. Inferred when omitted: children/hasChildren ⇒ folder, else file. */
+    kind?: 'folder' | 'file';
+    /** Explicit glyph name override (else inferred: folder/folder-open, or file type). */
+    icon?: string;
+    /** Nested children. A folder with no children is still expandable if `hasChildren`. */
+    children?: FolderNode[];
+    /** Lazy: mark a folder expandable before its children are loaded. */
+    hasChildren?: boolean;
+    /** Non-interactive row (no select / no check), still focusable for reading. */
+    disabled?: boolean;
+}
+
+export declare function FolderTree({ data, label, expandedIds, defaultExpandedIds, onExpandedChange, selectedId, defaultSelectedId, onSelect, checkable, checkedIds, defaultCheckedIds, onCheckedChange, filter, onFilterChange, onLoadChildren, className, }: FolderTreeProps): JSX.Element;
+
+export declare interface FolderTreeProps {
+    /** The forest — one or more roots. */
+    data: FolderNode[];
+    /** Accessible name for the tree (announced by screen readers). */
+    label?: string;
+    expandedIds?: string[];
+    defaultExpandedIds?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    selectedId?: string;
+    defaultSelectedId?: string;
+    onSelect?: (id: string, node: FolderNode) => void;
+    checkable?: boolean;
+    checkedIds?: string[];
+    defaultCheckedIds?: string[];
+    onCheckedChange?: (ids: string[]) => void;
+    filter?: boolean | string;
+    onFilterChange?: (query: string) => void;
+    onLoadChildren?: (node: FolderNode) => FolderNode[] | Promise<FolderNode[]>;
+    className?: string;
+}
+
 export { FontWeightToken }
 
 /**