division-ds 0.1.0 → 0.1.1

package/AGENTS.md

@@ -60,7 +60,7 @@ docs write `src/components/atoms/button/Button`, and from `src/pages/Screen.tsx`
 `'../lib/money'` from there. The tier barrels (`components/atoms`, `/molecules`,
 `/organisms`) are for the system's own composition; the organisms barrel pulls the chart library
 into whatever imports it. Icons come from `lucide-react`, with `aria-hidden="true"` unless the
-icon is the only content.
+icon is the only content. Installed with shadcn, paths start `src/division-ds/` instead of `src/`.
 
 **Colour.** Every colour is a semantic token inside a Tailwind arbitrary value:
 `text-[var(--color-text-primary)]`, `bg-[var(--color-surface-base)]`. Never a hex, never
@@ -69,9 +69,10 @@ have not seen in `llms-tokens.txt`. An invented name fails silently in the brows
 `npm run verify`.
 
 **Providers.** One `<Toaster>` and one `<TooltipProvider>` sit at the root of the app (`AppShell`,
-`DemoLayout`). Assume both, including for a screen you are writing that is not mounted anywhere
-yet: it will be mounted under one of the two shells. Call `useToast()` freely; do not mount a
-second `Toaster`, and do not drop a toast or a tooltip because you cannot see the provider.
+`DemoLayout` in this repository). Assume both, including for a screen you are writing that is not
+mounted anywhere yet: it will be mounted under one of the two shells. Call `useToast()` freely; do
+not mount a second `Toaster`, and do not drop a toast or a tooltip because you cannot see the
+provider. A project that uses the components mounts both itself (step 4 of `install.md`).
 
 **Focus.** Anything focusable that you style yourself gets
 `focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]`.
@@ -106,7 +107,8 @@ is the default. Tokens switch on their own, so a screen built from tokens needs
 The shell paints the page background (`surface.base`) and supplies the gutter; a screen sets its
 own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
 exception: it paints `surface.base` on itself, so its field colours never depend on what is
-behind it.
+behind it. In a project that uses the components, your own root does this
+(step 4 of `install.md`).
 
 **Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
 default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is
@@ -119,15 +121,17 @@ and spacing utilities are fine; only colour is restricted to tokens.
 **Cards.** To highlight or select a `Card`, set the border inline with a token:
 `style={{ border: '2px solid var(--color-accent-signal-fill)' }}`. A border utility class does
 not win against the panel's own border. `interactive` is only for a card that holds one link or
-button.
+button; give that link `className={cardLinkClass}` (from `Card`) to stretch it over the card.
 
 **Links.** Components that render links take `renderLink`, defaulting to a plain `<a>`. Under a
-router, pass an adapter (`src/demo/routerLink.tsx` is the example). No component imports a router.
+router, pass an adapter: `({ href, ...rest }) => <Link to={href} {...rest} />`. No component
+imports a router.
 
 **Charts and bundle size.** `ChartPanel` and `Sparkline` bring in recharts, a few hundred kB.
 Load the route or screen that uses them with `React.lazy` and a `<Suspense>` fallback, so recharts
 lands in its own chunk and screens without a chart never download it. Without that, Vite warns
-about a chunk over 500 kB; the warning is about load time only, and the build is fine.
+about a chunk over 500 kB; the warning is about load time only, and the build is fine. On a
+live page, data may change as often as you like: a chart animates its first draw only.
 
 <!-- topic: forms -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Checks a project that uses Division DS components: raw colours, invented tokens, touching buttons, unknown props.",
   "license": "MIT",
   "author": "Victor Ilioiu",

package/public/manifest/components.json

@@ -3861,7 +3861,8 @@
             "CardFooter",
             "CardHeader",
             "CardMedia",
-            "CardTitle"
+            "CardTitle",
+            "cardLinkClass"
           ],
           "from": "src/components/molecules/card/Card"
         }
@@ -3918,6 +3919,14 @@
           "description": "Passed through to the Card root DOM element."
         }
       ],
+      "api": [
+        {
+          "name": "cardLinkClass",
+          "kind": "const",
+          "code": "/** The stretched link an interactive card needs, for the `a` (or button) in its title: the link\n *  is the name's own, its `::after` covers the card, and the focus ring is drawn there, around the\n *  whole card. The shape ProductCard uses. Exported so a consumer never copies the string. */\nexport const cardLinkClass =\n  \"outline-none hover:underline underline-offset-2 after:absolute after:inset-0 after:content-[''] focus-visible:after:outline-2 focus-visible:after:outline-offset-2 focus-visible:after:outline-[var(--color-focus-ring)]\"",
+          "from": "src/components/molecules/card/Card"
+        }
+      ],
       "keyboard": [
         {
           "keys": [
@@ -4012,7 +4021,7 @@
         },
         {
           "caption": "Interactive: the whole card is one link. Hover over it, or press Tab to reach it",
-          "source": "const STRETCHED =\n  \"outline-none hover:underline underline-offset-2 after:absolute after:inset-0 after:content-[''] focus-visible:after:outline-2 focus-visible:after:outline-offset-2 focus-visible:after:outline-[var(--color-focus-ring)]\"\n\nfunction DepotLink({ title, note, href }: { title: string; note: string; href: string }) {\n  return (\n    <Card interactive className=\"h-full\">\n      <CardBody className=\"flex flex-col gap-1\">\n        <CardTitle>\n          <a href={href} className={STRETCHED}>\n            {title}\n          </a>\n        </CardTitle>\n        <CardDescription>{note}</CardDescription>\n      </CardBody>\n    </Card>\n  )\n}\n\n<div className=\"grid grid-cols-1 sm:grid-cols-3 gap-4 w-full\">\n  <DepotLink title=\"Ridge depot\" note=\"Open until 18:00. Twelve kits ready.\" href=\"#ridge-depot\" />\n  <DepotLink title=\"Quarry depot\" note=\"Open until 20:00. Four kits ready.\" href=\"#quarry-depot\" />\n  <DepotLink title=\"Mill depot\" note=\"Closed today. Opens tomorrow, 08:00.\" href=\"#mill-depot\" />\n</div>"
+          "source": "function DepotLink({ title, note, href }: { title: string; note: string; href: string }) {\n  return (\n    <Card interactive className=\"h-full\">\n      <CardBody className=\"flex flex-col gap-1\">\n        <CardTitle>\n          <a href={href} className={cardLinkClass}>\n            {title}\n          </a>\n        </CardTitle>\n        <CardDescription>{note}</CardDescription>\n      </CardBody>\n    </Card>\n  )\n}\n\n<div className=\"grid grid-cols-1 sm:grid-cols-3 gap-4 w-full\">\n  <DepotLink title=\"Ridge depot\" note=\"Open until 18:00. Twelve kits ready.\" href=\"#ridge-depot\" />\n  <DepotLink title=\"Quarry depot\" note=\"Open until 20:00. Four kits ready.\" href=\"#quarry-depot\" />\n  <DepotLink title=\"Mill depot\" note=\"Closed today. Opens tomorrow, 08:00.\" href=\"#mill-depot\" />\n</div>"
         },
         {
           "caption": "As a section",
@@ -8311,6 +8320,12 @@
           "default": "[]",
           "description": "Line and bar only. Shades stretches of the x-axis, such as night hours on a 24-hour chart. from and to are x-axis values (values of xKey), both included. When from comes after to in the data, the band wraps past the end: 22:00 to 06:00 shades 22:00 to the last point and the first point to 06:00. A band naming a value that isn't in the data is skipped. Every band is listed under the chart with its label, so screen readers hear it too."
         },
+        {
+          "name": "limits",
+          "type": "{ value: number; label?: string }[]",
+          "default": "[]",
+          "description": "Line and bar only, not at size sm. Draws a dashed horizontal line at a y value, such as an alert limit of 35 µg/m³. The y-axis grows to include it, so a limit above every data point stays in view. Every limit is listed under the chart with its label and its value formatted by formatValue, so screen readers hear it too."
+        },
         {
           "name": "headingLevel",
           "type": "2 | 3 | 4",
@@ -8419,7 +8434,7 @@
         },
         {
           "caption": "A shaded band: night hours on a 24-hour series (the band wraps past midnight)",
-          "source": "type Hour = { hour: string; pm25: number }\n\nconst PM25 = [9, 8, 7, 7, 8, 11, 17, 26, 31, 24, 18, 15, 14, 13, 14, 16, 21, 29, 34, 27, 19, 14, 11, 10]\n\nconst HOURS: Hour[] = PM25.map((pm25, hour) => ({ hour: `${String(hour).padStart(2, '0')}:00`, pm25 }))\n\n<ChartPanel<Hour>\n  title=\"Fine particles today\"\n  summary=\"PM2.5 peaked at the morning and evening rush hours, 31 and 34 µg/m³, and stayed lowest overnight.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  data={HOURS}\n  xKey=\"hour\"\n  xLabel=\"Hour\"\n  series={[{ key: 'pm25', label: 'PM2.5 (µg/m³)' }]}\n  bands={[{ from: '22:00', to: '06:00', label: 'Night' }]}\n  headingLevel={4}\n/>"
+          "source": "type Hour = { hour: string; pm25: number }\n\nconst PM25 = [9, 8, 7, 7, 8, 11, 17, 26, 31, 24, 18, 15, 14, 13, 14, 16, 21, 29, 34, 27, 19, 14, 11, 10]\n\nconst HOURS: Hour[] = PM25.map((pm25, hour) => ({ hour: `${String(hour).padStart(2, '0')}:00`, pm25 }))\n\n<ChartPanel<Hour>\n  title=\"Fine particles today\"\n  summary=\"PM2.5 peaked at the morning and evening rush hours, 31 and 34 µg/m³, and stayed lowest overnight.\"\n  kind=\"line\"\n  area\n  curve=\"smooth\"\n  data={HOURS}\n  xKey=\"hour\"\n  xLabel=\"Hour\"\n  series={[{ key: 'pm25', label: 'PM2.5 (µg/m³)' }]}\n  bands={[{ from: '22:00', to: '06:00', label: 'Night' }]}\n  limits={[{ value: 35, label: 'Alert limit (µg/m³)' }]}\n  headingLevel={4}\n/>"
         },
         {
           "caption": "Small: stat cards, each with a sparkline (a tiny line chart with no axes)",