@hadoku/themes 0.0.0-stage → 5.12.16

package/scripts/normalize-tokens.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Rewrites themes/src/style.css to the canonical symmetric token set.
+ *
+ * Every theme block currently opens with exactly 38 contiguous `--color-*`
+ * declarations followed by shadow/spacing/advanced tokens. This replaces that
+ * leading span with the generated canonical set and leaves everything after
+ * it byte-identical.
+ *
+ * Idempotent: running it twice produces the same file.
+ *
+ *   node themes/scripts/normalize-tokens.mjs [--dry]
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  STYLE_PATH,
+  readBlocks,
+  themesForSelector,
+  readDeclarations,
+  FAMILIES
+} from './lib/parse-themes.mjs'
+import { deriveTheme } from './lib/derive.mjs'
+
+const dry = process.argv.includes('--dry')
+const css = readFileSync(STYLE_PATH, 'utf8')
+const eol = css.includes('\r\n') ? '\r\n' : '\n'
+
+const FAMILY_LABEL = {
+  primary: 'Primary',
+  success: 'Success',
+  warning: 'Warning',
+  danger: 'Danger',
+  neutral: 'Neutral'
+}
+
+/** Render the canonical color declarations for one theme, with section comments. */
+function renderColors(tokens, indent) {
+  const lines = []
+  const push = s => lines.push(s ? indent + s : '')
+
+  for (const f of FAMILIES) {
+    push(`/* ${FAMILY_LABEL[f]} */`)
+    push(`--color-${f}: ${tokens[`--color-${f}`]};`)
+    push(`--color-${f}-dark: ${tokens[`--color-${f}-dark`]};`)
+    push(`--color-${f}-bg: ${tokens[`--color-${f}-bg`]};`)
+    push(`--color-${f}-hover: ${tokens[`--color-${f}-hover`]};`)
+    push(`--color-on-${f}: ${tokens[`--color-on-${f}`]};`)
+    push(`--color-on-${f}-bg: ${tokens[`--color-on-${f}-bg`]};`)
+    push('')
+  }
+
+  push('/* Text */')
+  for (const n of [
+    '--color-text',
+    '--color-text-secondary',
+    '--color-text-tertiary',
+    '--color-text-muted'
+  ]) {
+    push(`${n}: ${tokens[n]};`)
+  }
+  push('')
+  push('/* Borders */')
+  for (const n of ['--color-border', '--color-border-light']) push(`${n}: ${tokens[n]};`)
+  push('')
+  push('/* Backgrounds */')
+  for (const n of [
+    '--color-bg',
+    '--color-bg-card',
+    '--color-bg-alt',
+    '--color-bg-hover',
+    '--color-bg-overlay'
+  ]) {
+    push(`${n}: ${tokens[n]};`)
+  }
+
+  return lines.join(eol)
+}
+
+/* Collect edits first, apply back-to-front so earlier offsets stay valid. */
+const edits = []
+/* Values that changed for a reason other than a verbatim rename. */
+const changed = []
+
+for (const block of readBlocks(css)) {
+  const names = themesForSelector(block.selector)
+  if (!names.length) continue
+
+  const decls = readDeclarations(block.body)
+  const colorDecls = decls.filter(d => d.name.startsWith('--color-'))
+  if (!colorDecls.length) continue
+
+  const tokens = Object.fromEntries(decls.map(d => [d.name, d.value]))
+  const notes = []
+  const canonical = deriveTheme(tokens, notes)
+  for (const n of notes) changed.push({ theme: names[0], ...n })
+
+  // The color span covers whole lines: from the line holding the first
+  // `--color-` declaration through the line closing the last one.
+  const body = block.body
+  const firstAt = body.indexOf('--color-')
+  const lastName = colorDecls[colorDecls.length - 1].name
+  const endInBody = body.indexOf(';', body.lastIndexOf(lastName)) + 1
+
+  const lines = body.split(/\r?\n/)
+  const offsetOfLine = []
+  for (let i = 0, at = 0; i < lines.length; i += 1) {
+    offsetOfLine.push(at)
+    at += lines[i].length + eol.length
+  }
+  const lineOf = offset => {
+    let n = 0
+    while (n + 1 < offsetOfLine.length && offsetOfLine[n + 1] <= offset) n += 1
+    return n
+  }
+
+  let firstLine = lineOf(firstAt)
+  const lastLine = lineOf(endInBody - 1)
+
+  // Section comments inside the span get regenerated, but the first one sits
+  // on the line above it — pull it in so it isn't left orphaned.
+  if (firstLine > 0 && /^\s*\/\*[^*]*\*\/\s*$/.test(lines[firstLine - 1])) firstLine -= 1
+
+  const indent = lines[lineOf(firstAt)].match(/^[ \t]*/)[0]
+
+  edits.push({
+    start: block.start + offsetOfLine[firstLine],
+    end: block.start + endInBody,
+    text: renderColors(canonical, indent),
+    theme: names.join('+')
+  })
+}
+
+let out = css
+for (const e of edits.sort((a, b) => b.start - a.start)) {
+  out = out.slice(0, e.start) + e.text + out.slice(e.end)
+}
+
+console.log(`Rewrote ${edits.length} theme blocks.`)
+
+if (changed.length) {
+  console.log(
+    `\n${changed.length} value(s) adjusted for contrast (everything else carried over verbatim):`
+  )
+  for (const c of changed) {
+    const why =
+      c.reason === 'contrast'
+        ? 'authored value broke the on-<f> contract'
+        : c.reason === 'separation'
+          ? 'surface step under its floor'
+          : `dead-zone nudge, ΔL -${c.shift.toFixed(3)}`
+    console.log(`  ${c.theme.padEnd(17)} ${c.token.padEnd(24)} ${c.from} → ${c.to}   (${why})`)
+  }
+}
+
+if (dry) {
+  console.log('--dry: not writing.')
+} else {
+  writeFileSync(STYLE_PATH, out)
+  console.log(`Wrote ${STYLE_PATH}`)
+}

package/src/advanced.css

@@ -0,0 +1,218 @@
+/**
+ * Hadoku Themes — Advanced Visual Kit
+ *
+ * Class hooks for themes that ship an advanced visual contract
+ * (gradient + animated effects). Per-theme tokens live inside that
+ * theme's [data-theme='X'] block in style.css; this file is the
+ * shared rendering kit.
+ *
+ * Mode is controlled by data-theme-mode='simple' | 'advanced':
+ *   - 'simple' (default): flatten to the theme's solid colors
+ *   - 'advanced':         render the gradient + effects (opt-in)
+ *
+ * Class hooks (consumer applies these in JSX):
+ *   .hdk-advanced-page      — viewport-fixed gradient page background
+ *   .hdk-advanced-surface   — "window into the gradient" element
+ *   .hdk-advanced-surface--shift         — gradient displacement on hover
+ *   .hdk-advanced-surface--cascade-rich  — multi-wave shimmer
+ *   .hdk-advanced-surface--sat-rich      — saturation + cascade
+ *
+ * When --advanced-gradient is undefined (theme has no advanced
+ * contract), the surfaces fall back to their flat backgrounds so the
+ * classes are safe to apply unconditionally.
+ */
+
+/* ---------- Page surface ---------- */
+
+.hdk-advanced-page {
+  background: var(--advanced-gradient, var(--color-bg));
+  background-attachment: fixed;
+}
+
+/* ---------- Card surface ---------- */
+/* Each surface is its own stacking context so effect ::after layers
+   sit above the bg but below content without forcing children to set
+   z-index. */
+
+.hdk-advanced-surface {
+  position: relative;
+  overflow: hidden;
+  background: var(--advanced-gradient, var(--color-bg-card));
+  background-attachment: fixed;
+  isolation: isolate;
+}
+
+/* ---------- Effect: SHIFT — gradient displacement on hover ---------- */
+
+.hdk-advanced-surface--shift::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: var(--advanced-gradient);
+  background-attachment: scroll;
+  background-size: 130% 130%;
+  background-position: 30% 30%;
+  opacity: 0;
+  transition:
+    opacity 0.4s ease,
+    background-position 0.8s ease-out;
+  pointer-events: none;
+  z-index: -1;
+}
+
+.hdk-advanced-surface--shift:hover::after {
+  opacity: 1;
+  background-position: 70% 70%;
+}
+
+/* ---------- Effect: CASCADE-RICH — multi-wave, varied speeds ---------- */
+
+.hdk-advanced-surface--cascade-rich::before {
+  content: '';
+  position: absolute;
+  inset: -80%;
+  background: linear-gradient(
+    135deg,
+    transparent 38%,
+    rgba(255, 255, 255, 0.03) 44%,
+    rgba(255, 255, 255, 0.03) 48%,
+    transparent 54%
+  );
+  transform: translateX(-50%) translateY(-50%);
+  opacity: 0;
+  transition:
+    transform 1.2s ease-out,
+    opacity 0.2s ease;
+  pointer-events: none;
+  z-index: -1;
+}
+
+.hdk-advanced-surface--cascade-rich::after {
+  content: '';
+  position: absolute;
+  inset: -150%;
+  background: linear-gradient(
+    135deg,
+    transparent 0%,
+    transparent 22%,
+    rgba(255, 255, 255, 0.05) 26%,
+    transparent 30%,
+    transparent 40%,
+    rgba(255, 255, 255, 0.12) 45%,
+    rgba(255, 255, 255, 0.18) 48%,
+    rgba(255, 255, 255, 0.12) 51%,
+    transparent 56%,
+    transparent 66%,
+    rgba(255, 255, 255, 0.06) 70%,
+    transparent 74%,
+    transparent 100%
+  );
+  transform: translateX(-45%) translateY(-45%);
+  opacity: 0;
+  transition:
+    transform 4s cubic-bezier(0.22, 0.61, 0.36, 1) 0.1s,
+    opacity 0.5s ease 0.1s;
+  pointer-events: none;
+  z-index: -1;
+}
+
+.hdk-advanced-surface--cascade-rich:hover::before {
+  transform: translateX(50%) translateY(50%);
+  opacity: 1;
+}
+
+.hdk-advanced-surface--cascade-rich:hover::after {
+  transform: translateX(45%) translateY(45%);
+  opacity: 1;
+}
+
+/* ---------- Effect: SAT-RICH — saturation boost + 4-band cascade ---------- */
+
+.hdk-advanced-surface--sat-rich {
+  filter: saturate(1) brightness(1);
+  transition:
+    filter 0.6s ease-out,
+    box-shadow 0.6s ease-out;
+}
+
+.hdk-advanced-surface--sat-rich::after {
+  content: '';
+  position: absolute;
+  inset: -100%;
+  background: linear-gradient(
+    135deg,
+    transparent 20%,
+    rgba(255, 255, 255, 0.03) 30%,
+    transparent 38%,
+    transparent 44%,
+    rgba(255, 255, 255, 0.1) 50%,
+    rgba(255, 255, 255, 0.16) 52%,
+    rgba(255, 255, 255, 0.1) 54%,
+    transparent 60%,
+    transparent 70%,
+    rgba(255, 255, 255, 0.04) 78%,
+    transparent 86%
+  );
+  transform: translateX(-50%) translateY(-50%);
+  opacity: 0;
+  transition:
+    transform 3s ease-out,
+    opacity 0.6s ease-out;
+  pointer-events: none;
+  z-index: -1;
+}
+
+.hdk-advanced-surface--sat-rich:hover {
+  filter: saturate(1.15) brightness(1.05);
+  box-shadow:
+    0 4px 16px rgba(0, 0, 0, 0.1),
+    inset 0 0 0 1px rgba(255, 255, 255, 0.18);
+}
+
+.hdk-advanced-surface--sat-rich:hover::after {
+  transform: translateX(50%) translateY(50%);
+  opacity: 1;
+}
+
+/* ---------- Simple mode override ---------- */
+/* Forces flat colors regardless of theme. The selectors target
+   common scope roots so the override applies whether the attribute
+   is set on documentElement, body, or a microfrontend container. */
+
+[data-theme-mode='simple'] .hdk-advanced-page,
+[data-theme-mode='simple'].hdk-advanced-page {
+  background: var(--color-bg);
+  background-attachment: scroll;
+}
+
+[data-theme-mode='simple'] .hdk-advanced-surface,
+[data-theme-mode='simple'].hdk-advanced-surface {
+  background: var(--color-bg-card);
+  background-attachment: scroll;
+}
+
+[data-theme-mode='simple'] .hdk-advanced-surface::before,
+[data-theme-mode='simple'] .hdk-advanced-surface::after,
+[data-theme-mode='simple'].hdk-advanced-surface::before,
+[data-theme-mode='simple'].hdk-advanced-surface::after {
+  display: none;
+}
+
+[data-theme-mode='simple'] .hdk-advanced-surface--sat-rich:hover,
+[data-theme-mode='simple'].hdk-advanced-surface--sat-rich:hover {
+  filter: none;
+  box-shadow: none;
+}
+
+/* ---------- Reduced motion ---------- */
+
+@media (prefers-reduced-motion: reduce) {
+  .hdk-advanced-surface--shift::after,
+  .hdk-advanced-surface--cascade-rich::before,
+  .hdk-advanced-surface--cascade-rich::after,
+  .hdk-advanced-surface--sat-rich,
+  .hdk-advanced-surface--sat-rich::after {
+    transition: none;
+  }
+}

package/src/icons/Icon.tsx

@@ -0,0 +1,151 @@
+/**
+ * React `<Icon>` — a thin wrapper over the string registry.
+ *
+ * The glyph is emitted as real JSX children rather than dangerouslySetInnerHTML: the
+ * markup is ours and build-time-generated, but React apps run under the same strict
+ * CSP as the frontpage, and parsing 78 vendored strings at runtime buys nothing when
+ * the shapes can be elements. So the paths are parsed once, lazily, per icon actually
+ * rendered — an app that uses six icons never touches the other seventy-two.
+ */
+import React from 'react'
+import { ICON_MARKUP } from './registry.generated'
+import type { IconName } from './registry.generated'
+import type { IconFamily, IconVariant } from './index'
+
+export interface IconProps {
+  name: IconName
+  /** CSS length. Defaults to `1em` so the glyph scales with surrounding text. */
+  size?: string | number
+  /**
+   * Which family token colours this icon. Applies to `accent` (the glyph itself)
+   * and to `tint`/`filled` (the tile). Ignored for `bare`, which inherits
+   * `currentColor` by design.
+   */
+  family?: IconFamily
+  /** `bare` (default), `accent`, `tint`, or `filled` — see IconVariant. */
+  variant?: IconVariant
+  /** Round the accent tile. No effect when `variant` is `bare`. */
+  round?: boolean
+  /**
+   * Accessible name. Omit for decorative icons — those render `aria-hidden` so a
+   * screen reader does not announce a glyph that repeats an adjacent text label.
+   */
+  title?: string
+  className?: string
+  /** Stroke width in the 24x24 viewBox. Lucide's default is 2. */
+  strokeWidth?: number
+}
+
+/** `<path d="..." />` etc. -> React elements. Parsed once per icon, then cached. */
+const parsed = new Map<IconName, React.ReactNode[]>()
+
+const SELF_CLOSING = /<([a-z]+)\s+([^>]*?)\/>/g
+const ATTR = /([a-z-]+)="([^"]*)"/g
+
+/** SVG presentation attributes we emit, mapped to their React prop names. */
+const PROP_NAMES: Record<string, string> = {
+  d: 'd',
+  cx: 'cx',
+  cy: 'cy',
+  r: 'r',
+  x: 'x',
+  y: 'y',
+  x1: 'x1',
+  x2: 'x2',
+  y1: 'y1',
+  y2: 'y2',
+  rx: 'rx',
+  ry: 'ry',
+  width: 'width',
+  height: 'height',
+  points: 'points',
+  transform: 'transform',
+  fill: 'fill'
+}
+
+function parseMarkup(name: IconName): React.ReactNode[] {
+  const cached = parsed.get(name)
+  if (cached) return cached
+
+  const nodes: React.ReactNode[] = []
+  const markup = ICON_MARKUP[name]
+  let match: RegExpExecArray | null
+  SELF_CLOSING.lastIndex = 0
+  let i = 0
+  while ((match = SELF_CLOSING.exec(markup)) !== null) {
+    const [, tag, attrString] = match
+    const props: Record<string, string> = { key: String(i++) }
+    let attr: RegExpExecArray | null
+    ATTR.lastIndex = 0
+    while ((attr = ATTR.exec(attrString)) !== null) {
+      const prop = PROP_NAMES[attr[1]]
+      if (prop) props[prop] = attr[2]
+    }
+    nodes.push(React.createElement(tag, props))
+  }
+  parsed.set(name, nodes)
+  return nodes
+}
+
+export const Icon: React.FC<IconProps> = ({
+  name,
+  size = '1em',
+  family = 'warning',
+  variant = 'bare',
+  round = false,
+  title,
+  className,
+  strokeWidth = 2
+}) => {
+  if (ICON_MARKUP[name] === undefined) {
+    throw new Error(
+      `<Icon>: "${String(name)}" is not in the icon registry. ` +
+        `Add it to themes/src/icons/sources.json and run \`pnpm run generate:icons\`.`
+    )
+  }
+
+  const dim = typeof size === 'number' ? `${size}px` : size
+  const a11y = title
+    ? ({ role: 'img', 'aria-label': title } as const)
+    : ({ 'aria-hidden': true, focusable: 'false' } as const)
+
+  // `bare` and `accent` render the <svg> as the outermost element, so the caller's
+  // className belongs on it. `tint`/`filled` wrap it in a tile, and the className
+  // goes there instead — in both cases it lands on the element you get back.
+  const isTile = variant === 'tint' || variant === 'filled'
+  const svgClass = [
+    'hdk-icon',
+    variant === 'accent' ? `hdk-icon--${family}` : '',
+    !isTile && className ? className : ''
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  const svg = (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      className={svgClass}
+      width={dim}
+      height={dim}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...a11y}
+    >
+      {title ? <title>{title}</title> : null}
+      {parseMarkup(name)}
+    </svg>
+  )
+
+  if (!isTile) return svg
+
+  const tile =
+    `hdk-icon-tile hdk-icon-tile--${variant} hdk-icon-tile--${family}` +
+    (round ? ' hdk-icon-tile--round' : '') +
+    (className ? ` ${className}` : '')
+
+  return <span className={tile}>{svg}</span>
+}