torch-glare 2.5.5 → 2.6.0

package/docs/explanation/architecture.md

@@ -1,54 +0,0 @@
----
-title: Architecture
-description: How TORCH Glare is structured — the copy-in distribution model, the CLI, and the registry.
-group: explanation
-keywords: [architecture, copy-in, cli, registry, shadcn]
----
-
-# Architecture
-
-## Copy-in distribution
-
-TORCH Glare does **not** ship compiled components you import from a package. Instead, the
-published `torch-glare` package contains a CLI plus the raw component source, and
-`npx torch-glare add <Component>` copies that source into your project. This is the same
-model popularized by shadcn/ui.
-
-Consequences:
-
-- **You own the code.** Copied components live in your repo and can be edited freely.
-- **No runtime package dependency.** You import from your own path (`@/components/…`), not
-  from `torch-glare`.
-- **Explicit dependencies.** `add` also copies the component's internal dependencies
-  (nested components, hooks, utils) and installs required npm packages such as `@radix-ui/*`.
-
-## The registry
-
-The dependency graph is described by a generated manifest, `apps/lib/registry.json`. Each
-entry lists a component's npm dependencies and its internal (component/hook/util)
-dependencies. The CLI reads this manifest to resolve the full closure to copy when you run
-`add`, so results are deterministic and testable rather than inferred at install time.
-
-The registry is generated from source (`pnpm run registry`) and validated in CI, so it never
-drifts from the actual imports.
-
-## Layers
-
-| Layer | Location | Role |
-| --- | --- | --- |
-| Components | `components/` | UI built with Radix primitives + CVA variants. |
-| Hooks | `hooks/` | Reusable behavior (e.g. `useClickOutside`). |
-| Utils | `utils/` | Helpers like `cn` (class merging) and types. |
-| Providers | `providers/` | Context providers such as `ThemeProvider`. |
-| Layouts | `layouts/` | Composed page/section scaffolds. |
-
-## AI-facing docs
-
-`llms.txt`, `llms-full.txt`, and `llms-manifest.json` are generated from source
-(`pnpm run llms`) so assistants always get accurate component lists, dependencies, variants,
-and examples. A doc lint (`pnpm run check:ai-docs`) blocks incorrect usage patterns.
-
-## See also
-
-- [Design system](./design-system.md)
-- [CLI reference](../reference/cli.md)

package/docs/explanation/design-system.md

@@ -1,52 +0,0 @@
----
-title: Design System
-description: The conventions behind TORCH Glare — CVA variants, semantic tokens, sizing, and theming.
-group: explanation
-keywords: [design system, cva, variants, tokens, tailwind, sizing]
----
-
-# Design System
-
-TORCH Glare components share a small set of conventions so they compose predictably and
-theme uniformly.
-
-## Variants via CVA
-
-Component styling is defined with [class-variance-authority](https://cva.style) (`cva`). Each
-component exposes a `variant` and/or `size` prop whose allowed values come directly from its
-`cva` definition. For example, `Button` has variants
-`PrimeStyle, BluSecStyle, YelSecStyle, RedSecStyle, BorderStyle, PrimeContStyle, BluContStyle, RedContStyle`
-and sizes `S, M, L, XL`.
-
-Because variant names are the source of truth, docs and the `llms.*` files generate their
-variant lists from these definitions — they can't drift.
-
-## Semantic tokens
-
-Colors are addressed through semantic CSS variables, not raw hex, so a single component works
-across themes. Names follow a `--{category}-{context}-{component}-{state}` shape, e.g.
-`background-presentation-action-primary` or `content-presentation-state-negative`. Components
-reference these via Tailwind classes like `bg-background-presentation-action-secondary`.
-
-## Sizing scale
-
-Interactive components use a consistent `S / M / L / XL` scale (some also `XS`). Typography
-components such as `TransparentLabel` instead take a typography-scale `size`
-(e.g. `body-medium-regular`, `headers-large-bold`).
-
-## Theming
-
-Theme is driven by `data-theme` (`light | dark | default`) and `data-theme-mode`
-(`CSS | TORCH`). Every component accepts a `theme` prop for local overrides; app-wide theming
-uses `ThemeProvider`. See the [theme reference](../reference/theme.md).
-
-## Accessibility
-
-Interactive components build on Radix UI primitives for keyboard and ARIA behavior. Custom
-controls add the appropriate attributes directly (for example, a loading `Button` sets
-`aria-busy` and exposes its spinner with `role="status"`).
-
-## See also
-
-- [Architecture](./architecture.md)
-- [Theme reference](../reference/theme.md)

package/docs/how-to/form-and-list-recipes.md

@@ -1,386 +0,0 @@
----
-title: Form & List Page Recipes
-description: Production-tested patterns for building create dialogs, list pages, journal-line grids, and login layouts with TORCH Glare. Captures the "what actually ships" decisions for app-builders.
-keywords: [recipes, patterns, form, list, dialog, journal, line-items, login, filter-bar, grid]
----
-
-# Form & List Page Recipes
-
-Battle-tested layouts and component combinations from production frontend work.
-Use these as the starting point for create dialogs, list/filter pages,
-line-item grids, and login flows.
-
-> **For actual forms, reach for [`FormBuilder`](../components/form-builder.md) first.** The
-> multi-column form rows below are a layout escape hatch for the rare case that needs bespoke
-> positioning — they are **not** the default way to build a form. A normal create/edit form is
-> `FormBuilder` fields as JSX children with a resolver; see the
-> [Forms with FormBuilder](./forms-with-form-builder.md) guide. Don't hand-wire `FormField` /
-> `InputField` rows or hold field state in `useState` when `FormBuilder` would do it.
-
-> All examples use the `presentation` color tokens. Never substitute
-> `*-system-*` tokens or `variant="SystemStyle"` — see the rules banner at
-> the top of every doc response.
-
----
-
-## Recipe 1 — Multi-column form row with consistent baselines
-
-**Use case:** A row in a create dialog that mixes `InputField`, `Select`, and
-date inputs. Default heights don't match across components, so you have to
-opt in to alignment explicitly.
-
-```tsx
-<div className="grid grid-cols-3 gap-4">
-  <div className="flex flex-col gap-1.5">
-    <Label>Voucher Type *</Label>
-    <Select
-      className="w-full h-10"
-      value={type}
-      onValueChange={setType}
-      options={typeOptions}
-      placeholder="Select type"
-    />
-  </div>
-
-  <div className="flex flex-col gap-1.5">
-    <Label>Date *</Label>
-    <InputField
-      className="h-10"
-      type="date"
-      icon={<i className="ri-calendar-line text-base" />}
-      {...register("date")}
-    />
-  </div>
-
-  <div className="flex flex-col gap-1.5">
-    <Label>Fiscal Period *</Label>
-    <Select
-      className="w-full h-10"
-      value={period}
-      onValueChange={setPeriod}
-      options={periodOptions}
-      placeholder="Select period"
-    />
-  </div>
-</div>
-```
-
-Key rules:
-
-- **Every form control gets `h-10`** — both `InputField` and `Select` (which
-  also needs `w-full`).
-- **Wrap each field in `flex flex-col gap-1.5`**, not `space-y-1.5`, so labels
-  sit cleanly at the top of the row.
-- **Use `<InputField type="date">`** instead of a native `<input type="date">`
-  so you keep the icon slot and consistent styling.
-
----
-
-## Recipe 2 — List page with filter bar + data table
-
-**Use case:** Every list page (vouchers, accounts, bank accounts, etc.) needs
-the same filter bar — a search input + one or more select filters above a
-data table.
-
-```tsx
-{
-  /* Filter bar */
-}
-<div className="flex items-center gap-3">
-  <div className="flex-1 max-w-sm">
-    <InputField
-      className="h-10"
-      icon={<i className="ri-search-line text-base" />}
-      placeholder="Search..."
-      value={search}
-      onChange={(e) => setSearch(e.target.value)}
-    />
-  </div>
-
-  <SimpleSelect
-    className="w-48 h-10"
-    value={statusFilter || "ALL"}
-    onValueChange={(val) => setStatusFilter(val === "ALL" ? "" : val)}
-    options={[
-      { value: "ALL", label: "All Statuses" },
-      { value: "DRAFT", label: "Draft" },
-      { value: "POSTED", label: "Posted" },
-    ]}
-    placeholder="All Statuses"
-  />
-</div>;
-
-{
-  /* Data table */
-}
-<Card className="p-0 overflow-hidden">
-  <CardContent className="p-0 overflow-x-auto">
-    <Table className="w-full">
-      <TableHeader>
-        <TableRow>
-          <TableHead>Number</TableHead>
-          <TableHead>Status</TableHead>
-          <TableHead className="text-right">Total Debit</TableHead>
-          <TableHead className="text-right">Total Credit</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {rows.length === 0 ? (
-          <TableRow>
-            <TableCell
-              colSpan={4}
-              childrenClassName="flex flex-col items-center justify-center gap-3 py-12 w-full min-w-0 text-content-presentation-global-secondary"
-            >
-              <i className="ri-inbox-line text-4xl opacity-60" />
-              <p className="typography-body-medium-regular">No vouchers</p>
-              <p className="typography-body-small-regular opacity-80">Try adjusting your filters</p>
-            </TableCell>
-          </TableRow>
-        ) : (
-          rows.map((v) => (
-            <TableRow key={v.id}>
-              <TableCell className="whitespace-nowrap">{v.number}</TableCell>
-              <TableCell>{v.status}</TableCell>
-              <TableCell className="text-right font-mono whitespace-nowrap">
-                {v.totalDebit}
-              </TableCell>
-              <TableCell className="text-right font-mono whitespace-nowrap">
-                {v.totalCredit}
-              </TableCell>
-            </TableRow>
-          ))
-        )}
-      </TableBody>
-    </Table>
-  </CardContent>
-</Card>;
-```
-
-Key rules:
-
-- **Never use a native `<select>`** — `SimpleSelect` keeps styling consistent
-  with the rest of your forms.
-- **Never manually position a search icon with absolute positioning** —
-  `InputField`'s `icon` prop is built for this.
-- **Numeric columns get `text-right` on both `TableHead` and `TableCell`**,
-  plus `font-mono` on the cell so digits line up.
-- **Empty states use `childrenClassName`** on `TableCell` to bypass the
-  default `flex-row justify-start min-w-[200px]` wrapper. See `Table.md`
-  → "TableCell force-wraps children" for why.
-- **The "All / Any" filter option needs a sentinel value** (`"ALL"` here)
-  because Radix forbids `value=""`. See `SimpleSelect.md` for details.
-
----
-
-## Recipe 3 — Journal lines / line-item grid (display: contents)
-
-**Use case:** A repeating-row layout (journal lines, invoice line items,
-purchase order rows) with a header, N data rows, and a totals row — where
-columns must align across all rows.
-
-The naïve approach (each row is its own `display: grid`) breaks: short
-footer content collapses to a different width than long input content,
-and columns drift across rows. The fix is **one parent grid** with
-`className="contents"` on each row wrapper so the row's children become
-direct grid items of the parent.
-
-```tsx
-<div className="grid w-full grid-cols-[32px_minmax(0,2.5fr)_minmax(0,3fr)_minmax(0,1.5fr)_minmax(0,1.5fr)_36px] gap-x-3 gap-y-2 px-2">
-  {/* Header cells (direct grid items) */}
-  <div>#</div>
-  <div>Account</div>
-  <div>Description</div>
-  <div>Debit</div>
-  <div>Credit</div>
-  <div />
-
-  {/* Data rows — wrapper uses className="contents" so its children become
-      direct grid items of the parent grid */}
-  {lines.map((line, idx) => (
-    <div key={line.key} className="contents">
-      <div>{idx + 1}</div>
-      <Select
-        className="w-full h-10"
-        value={line.accountId}
-        onValueChange={(v) => updateLine(line.key, { accountId: v })}
-        options={accountOptions}
-      />
-      <InputField
-        className="h-10"
-        value={line.description}
-        onChange={(e) => updateLine(line.key, { description: e.target.value })}
-      />
-      <InputField
-        className="h-10 text-right font-mono"
-        type="number"
-        value={line.debit}
-        onChange={(e) => updateLine(line.key, { debit: e.target.value })}
-      />
-      <InputField
-        className="h-10 text-right font-mono"
-        type="number"
-        value={line.credit}
-        onChange={(e) => updateLine(line.key, { credit: e.target.value })}
-      />
-      <button onClick={() => removeLine(line.key)} aria-label="Delete row">
-        <i className="ri-delete-bin-line" />
-      </button>
-    </div>
-  ))}
-
-  {/* Totals row — direct grid items, no wrapper */}
-  <div />
-  <div />
-  <div className="text-right">Totals</div>
-  <div className="text-right font-mono">{totalDebit}</div>
-  <div className="text-right font-mono">{totalCredit}</div>
-  <div />
-</div>
-```
-
-Key rules:
-
-- **`className="contents"`** on the row wrapper is the critical trick. The
-  wrapper renders nothing of its own, so its children become direct grid
-  items of the parent.
-- **`minmax(0, Xfr)`** columns prevent content-driven blowout when a single
-  cell has a long value.
-- **Fixed-width columns** (the `32px` row-number column, the `36px` delete
-  column) are absolute pixel widths; flexible columns use `fr`.
-- **Header alignment**: Debit/Credit headers are `text-left` because the
-  column starts at the input's left edge — right-aligning the header would
-  visually disconnect it from the column. The values inside the input are
-  right-aligned via `text-right font-mono` on the input itself.
-
----
-
-## Recipe 4 — `DialogTitle` with icon
-
-**Use case:** Plain `<DialogTitle>Create Account</DialogTitle>` lacks visual
-hierarchy. Adding a relevant icon makes dialogs instantly recognizable.
-
-```tsx
-<DialogHeader>
-  <DialogTitle>
-    <div className="flex items-center gap-2">
-      <i className="ri-bank-line text-content-presentation-state-information" />
-      <span>Create Account</span>
-    </div>
-  </DialogTitle>
-</DialogHeader>
-```
-
-Pick an icon that matches the entity:
-
-| Entity               | Icon                 |
-| -------------------- | -------------------- |
-| Account              | `ri-bank-line`       |
-| Fiscal period / year | `ri-calendar-line`   |
-| Voucher / journal    | `ri-receipt-line`    |
-| Number series        | `ri-hashtag`         |
-| Posting rule         | `ri-settings-3-line` |
-| Exchange rate        | `ri-exchange-line`   |
-| Bank / cash account  | `ri-bank-card-line`  |
-
----
-
-## Recipe 5 — Two-column login layout
-
-**Use case:** A login page with brand panel on the left and form on the right.
-Communicates product identity better than a single centered card.
-
-```tsx
-import { Card, CardContent } from "@/components/Card";
-import { InputField } from "@/components/InputField";
-import { LoginButton } from "@/components/LoginButton";
-
-export function LoginPage() {
-  return (
-    <div className="grid min-h-screen grid-cols-1 lg:grid-cols-2">
-      {/* Brand panel — hidden on mobile */}
-      <div
-        className={[
-          "hidden lg:flex flex-col justify-center gap-6 p-12",
-          "bg-linear-to-br from-background-presentation-action-primary/20",
-          "via-background-presentation-form-base",
-          "to-background-presentation-state-information/10",
-        ].join(" ")}
-      >
-        <h1 className="typography-headers-large-medium">Welcome to Torch Finance</h1>
-        <ul className="flex flex-col gap-3">
-          {features.map((f) => (
-            <li key={f.title} className="flex items-start gap-3">
-              <span
-                className={[
-                  "mt-0.5 inline-flex h-6 w-6 items-center justify-center",
-                  "rounded-full bg-background-presentation-state-success-primary",
-                  "text-content-presentation-action-dark-primary",
-                ].join(" ")}
-              >
-                <i className="ri-check-line" />
-              </span>
-              <div>
-                <p className="typography-body-medium-medium">{f.title}</p>
-                <p className="typography-body-small-regular text-content-presentation-global-secondary">
-                  {f.description}
-                </p>
-              </div>
-            </li>
-          ))}
-        </ul>
-      </div>
-
-      {/* Form panel */}
-      <div className="flex items-center justify-center p-6">
-        <Card className="w-full max-w-md">
-          <CardContent className="flex flex-col gap-4 p-8">
-            <h2 className="typography-headers-medium-medium">Sign in</h2>
-
-            <InputField
-              className="h-10"
-              type="email"
-              icon={<i className="ri-mail-line text-base" />}
-              placeholder="Email"
-              errorMessage={errors.email?.message}
-              {...register("email")}
-            />
-
-            <InputField
-              className="h-10"
-              type={showPassword ? "text" : "password"}
-              icon={<i className="ri-lock-line text-base" />}
-              childrenSide={
-                <button
-                  type="button"
-                  onClick={() => setShowPassword((v) => !v)}
-                  aria-label={showPassword ? "Hide password" : "Show password"}
-                >
-                  <i className={showPassword ? "ri-eye-off-line" : "ri-eye-line"} />
-                </button>
-              }
-              placeholder="Password"
-              errorMessage={errors.password?.message}
-              {...register("password")}
-            />
-
-            <LoginButton isLoading={isSubmitting} type="submit">
-              Sign in
-            </LoginButton>
-          </CardContent>
-        </Card>
-      </div>
-    </div>
-  );
-}
-```
-
-Key rules:
-
-- **`hidden lg:flex`** hides the brand panel on mobile; the form panel
-  stretches to full width below the breakpoint.
-- **`bg-linear-to-br from-* via-* to-*`** is Tailwind v4 gradient syntax. For
-  v3 use `bg-gradient-to-br`.
-- **`LoginButton` has a built-in `isLoading` prop** — wire it to your form's
-  submitting state instead of writing your own loading spinner.
-- **Use `InputField`'s `childrenSide`** for the password show/hide toggle —
-  the slot is built for trailing actions like this.