@designtools/blocks 0.0.0-stage → 0.2.0

package/registry/lib/manifest-types.ts

@@ -0,0 +1,284 @@
+/**
+ * The manifest schema: what `designtools-manifest build` writes to
+ * `<system>/manifest/`: components.json, tokens.json, rules.json,
+ * patterns.json, taxonomy.json and assets.json.
+ *
+ * This file has no imports on purpose. @designtools/blocks carries a byte-identical
+ * copy, so a project's docs read the manifest through the same types the tool
+ * wrote it with, and a test in this repo fails if the two drift.
+ *
+ * Every path is relative to the project root, with forward slashes. Arrays keep
+ * source order where order means something (variant axes, fixture states, token
+ * ramps); everything else is sorted, so a diff of the files shows only real changes.
+ */
+
+export const MANIFEST_SCHEMA = "designtools.manifest/1";
+
+/** What every manifest file opens with. */
+interface ManifestFile {
+  /** `@designtools/manifest@<version>`, so `check` can tell a tool upgrade from an edit. */
+  generator: string;
+  schema: string;
+}
+
+/** components.json */
+export interface ComponentsManifest extends ManifestFile {
+  /** The system folder the components were read from. */
+  system: string;
+  /** Sorted by name, then source. */
+  components: ComponentEntry[];
+}
+
+export interface ComponentEntry {
+  /** The export name, or `@name` when the JSDoc gives one. */
+  name: string;
+  /** The exported identifier to import. Equals `name` unless `@name` renamed it. */
+  export: string;
+  /** The file that exports it. */
+  source: string;
+  /**
+   * The module specifier an app imports it by, through the tsconfig path alias
+   * that reaches the system folder (`@ds/button/button`). Absent when no alias does,
+   * in which case `source` is the only honest answer.
+   */
+  import?: string;
+  /** The component's JSDoc, or its variant config's when the component has none. */
+  description?: string;
+  /** `@category`. Blocks group components without one under "Components". */
+  category?: string;
+  /** `@status`, or `deprecated` from `@deprecated`. Absent until someone decides it. */
+  status?: Status;
+  /** Why it has that status: the `@deprecated` reason, or text after `@status`. */
+  statusNote?: string;
+  /** `@use`, `@avoid`, `@instead`: when to reach for it, when not, and what instead. */
+  usage?: Usage;
+  /** `@example` snippets in the JSDoc, each one JSX. */
+  snippets?: string[];
+  /** `@see`, each one a link or a component name. */
+  see?: string[];
+  /** `@primitive`: the primitive it wraps, as a link or a package path. */
+  primitive?: string;
+  /** `@aria`: the ARIA pattern it follows, usually a link. */
+  aria?: string;
+  /** `@role` and `@keyboard`: what assistive technology meets, and the keys it answers. */
+  a11y?: { role?: string; keyboard?: string[] };
+  /** `@replaces`: raw elements this component stands in for, which the adherence report counts. */
+  replaces?: string[];
+  /**
+   * What it also accepts beyond its own props: an intrinsic element (`"span"`)
+   * or a wrapped primitive (`"@base-ui/react/select:Root"`).
+   */
+  inherits?: string[];
+  /** Its own props, and those of a primitive it wraps. Inherited DOM props are left out. */
+  props: Record<string, PropEntry>;
+  /** Absent when it has no variants by any route. */
+  variants?: VariantsEntry;
+  /** Every `data-slot` it renders, sorted. */
+  slots: string[];
+  /** Absent when the component has no examples file. */
+  examples?: ExamplesEntry;
+}
+
+export type Status = "stable" | "emerging" | "deprecated";
+
+export interface Usage {
+  use?: string;
+  avoid?: string;
+  /** Components, or other things, to use instead. */
+  instead?: string[];
+}
+
+export interface PropEntry {
+  /** The type as written or resolved, e.g. `string`, `"sm" | "md"`, `(v: string) => void`. */
+  type: string;
+  /** Present when the type is a union of literals: each value, unquoted. */
+  values?: string[];
+  required: boolean;
+  /** The default, as source text, when the component destructures one. */
+  default?: string;
+  description?: string;
+  deprecated?: string;
+  /** The package that declares it, when it comes from a wrapped primitive rather than the project. */
+  from?: string;
+}
+
+export interface VariantsEntry {
+  /** Where the axes came from: a `tv()` or `cva()` config, or the props' literal union types. */
+  from: "tv" | "cva" | "props";
+  /** The config's variable name. Absent when `from` is `"props"`. */
+  config?: string;
+  /** Source order. */
+  axes: VariantAxis[];
+  /** Conditions only, without their classes, in source order. */
+  compound?: Record<string, string | string[]>[];
+  /** A `tv()` config's named parts, in source order. */
+  parts?: string[];
+}
+
+export interface VariantAxis {
+  name: string;
+  /** Source order. */
+  options: VariantOption[];
+  default?: string;
+}
+
+export interface VariantOption {
+  name: string;
+  description?: string;
+}
+
+/**
+ * A co-located `*.examples.tsx`: `canonical` is the one to copy, `do*` and
+ * `dont*` render as pairs in order, anything else is a further example.
+ */
+export interface ExamplesEntry {
+  source: string;
+  canonical?: ExampleRef;
+  do: ExampleRef[];
+  dont: ExampleRef[];
+  other: ExampleRef[];
+}
+
+export interface ExampleRef {
+  /** The export name. */
+  name: string;
+  /** Its JSDoc: why to do it, or why not. */
+  description?: string;
+  /** The JSX it returns, as written, for agents and code views. */
+  code?: string;
+}
+
+/** tokens.json */
+export interface TokensManifest extends ManifestFile {
+  /** The stylesheets read, in the order given. */
+  sources: string[];
+  /** Source order: file by file, declaration by declaration. */
+  tokens: TokenEntry[];
+}
+
+export type TokenTier =
+  | "color"
+  | "font"
+  | "font-weight"
+  | "text"
+  | "leading"
+  | "tracking"
+  | "spacing"
+  | "size"
+  | "radius"
+  | "shadow"
+  | "ease"
+  | "duration"
+  | "motion"
+  | "breakpoint"
+  | "container"
+  | "other";
+
+export interface TokenEntry {
+  /** The custom property, with its dashes: `--color-primary-500`. */
+  name: string;
+  tier: TokenTier;
+  /**
+   * The value in each context it is declared in. `default` is `@theme` or `:root`;
+   * `light` and `dark` are the mode blocks; a `p3:` prefix marks the
+   * `@media (color-gamut: p3)` layer. Any other selector is kept as written.
+   */
+  values: Record<string, string>;
+  /** The comment above it, or above the run of declarations it belongs to. */
+  description?: string;
+  /** The stylesheet that first declares it. */
+  source: string;
+  /** Later stylesheets whose declaration replaced a value, in the order read: an override layer. */
+  overriddenIn?: string[];
+}
+
+/** rules.json: brand and interface rules in one format. */
+export interface RulesManifest extends ManifestFile {
+  /** Sorted by id. */
+  rules: RuleEntry[];
+}
+
+export interface RuleEntry {
+  /** The file name without `.rule.json`, used as its anchor: `touch-target`. */
+  id: string;
+  kind: "brand" | "interface";
+  title: string;
+  /** The rule, in one or two sentences, for people first. */
+  statement: string;
+  /** Why it exists. */
+  rationale?: string;
+  /** The measurable line, e.g. `44 × 44 CSS px`. */
+  threshold?: string;
+  /** Components, elements, assets or pages it governs. */
+  appliesTo?: string[];
+  exceptions?: string[];
+  /** Tokens it rests on, e.g. `--size-2xl`. */
+  tokens?: string[];
+  /**
+   * Confirmed with the client, an assumption still to confirm, or measured: generated from the
+   * tokens (where a colour can be text), a fact that changes when they do, not a decision.
+   */
+  status: "confirmed" | "assumption" | "measured";
+  /** How it is proved: a test, a lint rule, an audit, or a person. */
+  check?: { kind: "test" | "lint" | "audit" | "manual"; ref?: string; description?: string };
+  source: string;
+}
+
+/** patterns.json: the product's recurring screen compositions. */
+export interface PatternsManifest extends ManifestFile {
+  /** Sorted by name. */
+  patterns: PatternEntry[];
+}
+
+export interface PatternEntry {
+  /** From the file name: `checkout` for `checkout.pattern.tsx`. */
+  id: string;
+  name: string;
+  description?: string;
+  status?: Status;
+  /** The system components it imports, by name, sorted. */
+  components: string[];
+  /** Each named export is a composition, in source order. */
+  examples: ExampleRef[];
+  source: string;
+}
+
+/** taxonomy.json: one vocabulary, with the wrong forms to avoid. */
+export interface TaxonomyManifest extends ManifestFile {
+  /** Sorted by name. */
+  terms: TermEntry[];
+}
+
+export interface TermEntry {
+  /** The canonical form. */
+  name: string;
+  kind: "component" | "variant" | "token" | "pattern" | "rule" | "product";
+  /** Known wrong forms: `error` for `destructive`, `Modal` for `Dialog`, "log in" for "sign in". */
+  wrong?: string[];
+  note?: string;
+  /** Where it is defined: a component's source, a token's name, a rule's id. */
+  ref?: string;
+}
+
+/** assets.json: logos, icons and imagery, with how to use them. */
+export interface AssetsManifest extends ManifestFile {
+  /** Sorted by file. */
+  assets: AssetEntry[];
+}
+
+export interface AssetEntry {
+  file: string;
+  kind: "logo" | "icon" | "image" | "other";
+  name: string;
+  usage?: string;
+  /** e.g. `24px tall` */
+  minSize?: string;
+  /** e.g. `the height of the wordmark's x` or a length */
+  clearSpace?: string;
+  /** Surfaces it may sit on, as semantic colour names: `canvas`, `primary`. */
+  surfaces?: string[];
+  alt?: string;
+  /** Intrinsic size, read from an SVG's viewBox or a PNG's header. */
+  width?: number;
+  height?: number;
+}

package/registry/lib/manifest.ts

@@ -0,0 +1,228 @@
+/**
+ * Reading the manifest: grouping components for navigation, and sorting tokens
+ * into the shapes the token blocks draw (semantic pairs, ramps, a type scale).
+ * Pure functions over the JSON; nothing here touches the DOM.
+ */
+
+import {
+  MANIFEST_SCHEMA,
+  type ComponentEntry,
+  type ComponentsManifest,
+  type TokenEntry,
+  type TokenTier,
+  type TokensManifest,
+} from "./manifest-types";
+
+/**
+ * A `components.json` import, typed and checked. A JSON import is typed by its
+ * literal contents, which do not line up with the schema, so read it through here.
+ */
+export function readComponents(json: unknown): ComponentsManifest {
+  checkSchema(json, "components.json");
+  return json as ComponentsManifest;
+}
+
+/** A `tokens.json` import, typed and checked. */
+export function readTokens(json: unknown): TokensManifest {
+  checkSchema(json, "tokens.json");
+  return json as TokensManifest;
+}
+
+function checkSchema(json: unknown, file: string) {
+  const schema = (json as { schema?: unknown } | null)?.schema;
+  if (schema !== MANIFEST_SCHEMA) {
+    throw new Error(
+      `${file} has schema ${String(schema)}; these blocks read schema ${MANIFEST_SCHEMA}. Rebuild it with a matching @designtools/manifest.`,
+    );
+  }
+}
+
+/** Where components without `@category` are listed. */
+export const DEFAULT_CATEGORY = "Components";
+
+/** The key the generated registry files a component under: `src/ds/badge/badge.tsx#Badge`. */
+export function componentKey(entry: Pick<ComponentEntry, "source" | "export">): string {
+  return `${entry.source}#${entry.export}`;
+}
+
+/** `RadioGroup` → `radio-group`, for URLs. */
+/**
+ * What an app writes to import it: the alias the manifest found (`@ds/button/button`),
+ * or the file's path when no alias reaches the system folder.
+ */
+export function importOf(entry: Pick<ComponentEntry, "import" | "source">): string {
+  return entry.import ?? entry.source.replace(/\.(tsx?|jsx?)$/, "");
+}
+
+export function slugOf(entry: Pick<ComponentEntry, "name">): string {
+  return entry.name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+export function findBySlug(manifest: ComponentsManifest, slug: string): ComponentEntry | undefined {
+  return manifest.components.find((c) => slugOf(c) === slug);
+}
+
+export interface CategoryGroup {
+  category: string;
+  components: ComponentEntry[];
+}
+
+/**
+ * Categories in name order, uncategorised last; components by name within each.
+ * A part without its own `@category` (CardHeader) joins the category of a
+ * component in the same file (Card), so a family stays together.
+ */
+export function groupByCategory(manifest: ComponentsManifest): CategoryGroup[] {
+  const fileCategory = new Map<string, string>();
+  for (const c of manifest.components) if (c.category && !fileCategory.has(c.source)) fileCategory.set(c.source, c.category);
+  const groups = new Map<string, ComponentEntry[]>();
+  for (const c of manifest.components) {
+    const key = c.category ?? fileCategory.get(c.source) ?? DEFAULT_CATEGORY;
+    groups.set(key, [...(groups.get(key) ?? []), c]);
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => (a === DEFAULT_CATEGORY ? 1 : b === DEFAULT_CATEGORY ? -1 : a < b ? -1 : a > b ? 1 : 0))
+    .map(([category, components]) => ({ category, components }));
+}
+
+export interface Family {
+  /** The component with the `@category`: Card. */
+  head: ComponentEntry;
+  /** The rest of its file, which has none of its own: CardHeader, CardTitle. */
+  parts: ComponentEntry[];
+}
+
+/**
+ * Each category's components with their parts folded under them, so a reader
+ * sees nine components rather than fourteen pages. A part is a component with
+ * no `@category` of its own in a file whose first categorised component heads it.
+ */
+export function groupFamilies(manifest: ComponentsManifest): { category: string; families: Family[] }[] {
+  return groupByCategory(manifest).map(({ category, components }) => {
+    const families: Family[] = [];
+    const heads = new Map<string, Family>();
+    for (const c of components) {
+      const head = heads.get(c.source);
+      if (head && !c.category) {
+        head.parts.push(c);
+        continue;
+      }
+      const family = { head: c, parts: [] };
+      families.push(family);
+      if (c.category && !heads.has(c.source)) heads.set(c.source, family);
+    }
+    // a part whose name sorts before its head's was listed before the head was known: it joins it now
+    const kept = families.filter((f) => {
+      const head = heads.get(f.head.source);
+      if (!head || head === f || f.head.category) return true;
+      head.parts.push(f.head);
+      return false;
+    });
+    for (const f of kept) f.parts.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { category, families: kept };
+  });
+}
+
+export function tokensOfTier(manifest: TokensManifest, tier: TokenTier): TokenEntry[] {
+  return manifest.tokens.filter((t) => t.tier === tier);
+}
+
+export type Mode = "light" | "dark";
+
+/** A token's value in a mode, falling back to its mode-invariant value. */
+export function valueIn(token: TokenEntry, mode: Mode): string | undefined {
+  return token.values[mode] ?? token.values.default;
+}
+
+export interface Ramp {
+  /** `primary` for `--color-primary-500`. */
+  family: string;
+  steps: { step: string; token: TokenEntry }[];
+}
+
+/** `--color-<family>-<step>` primitives, families in source order, steps as declared. */
+export function ramps(manifest: TokensManifest): Ramp[] {
+  const out = new Map<string, Ramp>();
+  for (const t of manifest.tokens) {
+    const m = /^--color-([a-z][\w-]*?)-(\d+)$/.exec(t.name);
+    if (!m) continue;
+    const ramp = out.get(m[1]) ?? { family: m[1], steps: [] };
+    ramp.steps.push({ step: m[2], token: t });
+    out.set(m[1], ramp);
+  }
+  return [...out.values()];
+}
+
+export interface SemanticColour {
+  /** `--primary` */
+  name: string;
+  background: TokenEntry;
+  /** `--primary-foreground`, when the generator paired one. */
+  foreground?: TokenEntry;
+}
+
+/**
+ * Semantic colours (unprefixed, mode-aware: `--primary`, `--canvas`), each with
+ * its foreground when it has one. The `--color-*` bridge that points Tailwind
+ * at them is left out: it is the same colour under a second name.
+ */
+export function semanticColours(manifest: TokensManifest): SemanticColour[] {
+  const colours = manifest.tokens.filter((t) => t.tier === "color" && !t.name.startsWith("--color-"));
+  const byName = new Map(colours.map((t) => [t.name, t]));
+  return colours
+    .filter((t) => !t.name.endsWith("-foreground"))
+    .map((background) => {
+      const foreground = byName.get(`${background.name}-foreground`);
+      return foreground ? { name: background.name, background, foreground } : { name: background.name, background };
+    });
+}
+
+export interface TypeStep {
+  /** `--text-sm` */
+  name: string;
+  size: TokenEntry;
+  lineHeight?: TokenEntry;
+  letterSpacing?: TokenEntry;
+  fontWeight?: TokenEntry;
+}
+
+/** `--text-*` sizes with the `--text-*--line-height` (and tracking, weight) Tailwind pairs with them. */
+export function typeScale(manifest: TokensManifest): TypeStep[] {
+  const text = tokensOfTier(manifest, "text");
+  const byName = new Map(text.map((t) => [t.name, t]));
+  return text
+    .filter((t) => !t.name.includes("--", 2) && !/shadow/.test(t.name))
+    .map((size) => {
+      const step: TypeStep = { name: size.name, size };
+      const lh = byName.get(`${size.name}--line-height`);
+      const ls = byName.get(`${size.name}--letter-spacing`);
+      const fw = byName.get(`${size.name}--font-weight`);
+      if (lh) step.lineHeight = lh;
+      if (ls) step.letterSpacing = ls;
+      if (fw) step.fontWeight = fw;
+      return step;
+    });
+}
+
+/** `--radius-md` → `md`; `--spacing` → `spacing`. */
+export function shortName(token: Pick<TokenEntry, "name">, prefix?: string): string {
+  const name = token.name.replace(/^--/, "");
+  return prefix && name.startsWith(`${prefix}-`) ? name.slice(prefix.length + 1) : name;
+}
+
+/**
+ * Descriptions run over several tokens (one comment above a group), so show a
+ * description only where it changes.
+ */
+export function withGroupDescriptions<T extends { description?: string }>(items: T[]): (T & { groupDescription?: string })[] {
+  let last: string | undefined;
+  return items.map((item) => {
+    const changed = item.description !== last;
+    last = item.description;
+    return changed && item.description ? { ...item, groupDescription: item.description } : item;
+  });
+}