@hadoku/themes 0.0.0-stage → 5.12.16

package/src/icons/emoji-map.json

@@ -0,0 +1,202 @@
+{
+  "$comment": [
+    "CANONICAL emoji -> icon name. The migration's single source of truth.",
+    "",
+    "This exists so `📋` resolves to `clipboard` in every repo instead of `clipboard`",
+    "in one and `paste` in the next. Twelve repos migrating independently would each",
+    "re-decide these, and the drift would be invisible until two apps sat side by side",
+    "on the frontpage showing different glyphs for the same idea.",
+    "",
+    "`check-icons` reads this to SUGGEST the replacement in its findings, which is what",
+    "turns each one from a decision into an edit. Keys are matched with variation",
+    "selectors stripped, so `⚙` and `⚙️` both land on `gear`.",
+    "",
+    "Every value must exist in sources.json — check-icons fails loudly if one does not."
+  ],
+
+  "$comment_ambiguous": [
+    "A FLAT MAP CANNOT RESOLVE THESE. One emoji, two right answers depending on what",
+    "sits next to it, so `$ambiguous` names them and both tools defer to a human:",
+    "the codemod refuses them outright, and check-icons prints the caveat under its",
+    "suggestion instead of presenting one arm of a pair as settled.",
+    "",
+    "`◀`/`▶` is the case that proved it. `▶` lives in the transport row below with",
+    "`⏸`/`⏭`/`⏮` because a play button really is `play` — hadoku-dataplatform's",
+    "VodPlayer renders `isPlaying ? <Icon name=\"pause\"/> : <Icon name=\"play\"/>`.",
+    "But `◀`/`▶` is just as often a mirrored nav pair, and there applying the map",
+    "arm by arm yields an outline chevron facing a filled triangle. That is exactly",
+    "how promptsmith shipped a mismatched tournament row, and how the same repo's",
+    "PartBadge `◀ ▶` had to be hand-corrected to chevron-left/chevron-right.",
+    "",
+    "Neither value can move without breaking the other site, so the ambiguity is",
+    "recorded here rather than papered over with a coin-flip default."
+  ],
+  "$ambiguous": {
+    "◀": "in a mirrored `◀ … ▶` pair use chevron-left WITH chevron-right — never pair it with play",
+    "▶": "play ONLY as a transport control beside ⏸; in a mirrored `◀ … ▶` pair use chevron-right"
+  },
+
+  "$comment_catalogue": "hadoku_site/spec/categories.json — the frontpage catalogue.",
+  "👋": "wave",
+  "📄": "document",
+  "📧": "mail",
+  "✉": "mail",
+  "🎨": "palette",
+  "🖨": "printer",
+  "✨": "sparkles",
+  "🎭": "masks",
+  "🔧": "wrench",
+  "📡": "antenna",
+  "🔍": "magnifier",
+  "🔎": "magnifier",
+  "💼": "briefcase",
+  "⚙": "gear",
+  "🖐": "helping-hand",
+  "✅": "check",
+  "✔": "tick",
+  "☑": "tick",
+  "🎬": "clapper",
+  "🍿": "popcorn",
+  "📼": "videotape",
+
+  "$comment_status": "State and feedback.",
+  "⚠": "warning",
+  "❌": "error",
+  "✖": "close",
+  "❎": "error",
+  "ℹ": "info",
+  "⏳": "hourglass",
+  "⌛": "hourglass",
+  "⏰": "clock",
+  "🕐": "clock",
+  "💤": "sleep",
+  "⚪": "circle",
+  "🔴": "circle-dot",
+  "🟢": "circle-dot",
+  "🟡": "circle-dot",
+  "🔵": "circle-dot",
+  "➖": "minus",
+  "🚨": "warning",
+  "🔥": "fire",
+  "💥": "warning",
+  "🎉": "party",
+  "🏆": "trophy",
+  "⭐": "star",
+  "🌟": "star",
+  "👍": "thumbs-up",
+  "👎": "thumbs-down",
+  "❤": "heart",
+  "🩷": "heart",
+  "🖤": "heart",
+
+  "$comment_actions": "Verbs — buttons and controls.",
+  "🗑": "trash",
+  "✏": "edit",
+  "📝": "note",
+  "📋": "clipboard",
+  "📌": "pin",
+  "🔄": "refresh",
+  "♻": "refresh",
+  "▶": "play",
+  "⏸": "pause",
+  "⏭": "next",
+  "⏮": "previous",
+  "⏹": "stop",
+  "🔀": "shuffle",
+  "🔗": "link",
+  "⛓": "link",
+  "👁": "eye",
+  "🔒": "lock",
+  "🔑": "key",
+  "🛡": "shield",
+  "🧹": "broom",
+  "🪄": "wand",
+  "🔔": "bell",
+  "🚩": "flag",
+  "🏷": "tag",
+  "🔖": "bookmark",
+  "📤": "upload",
+  "⬆": "arrow-up",
+  "📥": "download",
+  "⬇": "arrow-down",
+  "➡": "arrow-right",
+  "⬅": "arrow-left",
+  "↔": "arrows-horizontal",
+  "↗": "arrow-up-right",
+  "↩": "return",
+  "⤴": "branch-up",
+  "◀": "chevron-left",
+  "🔼": "chevron-up",
+  "🔽": "chevron-down",
+  "➕": "plus",
+  "📎": "copy",
+  "💾": "save",
+  "📨": "send",
+
+  "$comment_objects": "Nouns — things a screen is about.",
+  "📁": "folder",
+  "📂": "folder",
+  "📦": "package",
+  "📅": "calendar",
+  "🗓": "calendar",
+  "🖼": "image",
+  "📷": "camera",
+  "🎞": "film",
+  "🎵": "music",
+  "🎧": "music",
+  "🔊": "volume-high",
+  "🔈": "volume-low",
+  "🔇": "volume-mute",
+  "💬": "chat",
+  "📖": "book",
+  "📚": "book",
+  "🤝": "handshake",
+  "🤖": "robot",
+  "👤": "user",
+  "👥": "users",
+  "👑": "crown",
+  "💀": "skull",
+  "🐈": "cat",
+  "🦴": "bone",
+  "🎮": "gamepad",
+  "🧰": "toolbox",
+  "🧪": "flask",
+  "🏥": "hospital",
+  "🌐": "globe",
+  "🗺": "map",
+  "📊": "chart",
+  "📈": "chart",
+  "📉": "chart",
+  "📐": "crop",
+  "🖥": "desktop",
+  "💻": "desktop",
+  "🗄": "database",
+  "🗃": "database",
+  "⌨": "terminal",
+  "🧱": "layers",
+  "🎯": "target",
+  "🚀": "rocket",
+  "⚡": "zap",
+  "🧭": "compass",
+  "🏠": "home",
+  "🏡": "home",
+  "📭": "inbox",
+  "📬": "inbox",
+  "📮": "inbox",
+  "☀": "sun",
+  "🌙": "moon",
+  "🧑": "user",
+  "🙋": "wave",
+  "💡": "zap",
+  "🔦": "magnifier",
+  "📏": "crop",
+  "✂": "scissors",
+  "🩹": "wrench",
+  "🔨": "wrench",
+  "🛠": "toolbox",
+  "⚔": "toolbox",
+  "🏹": "target",
+  "🔱": "layers",
+  "🚫": "ban",
+  "⛔": "ban"
+}

package/src/icons/index.ts

@@ -0,0 +1,151 @@
+/**
+ * The enforced icon set — framework-free half.
+ *
+ * Every consumer references icons BY NAME from `IconName`. Nobody inlines their own
+ * SVG: an icon that is not in the registry does not exist, which is what keeps 16 apps
+ * rendering the same pictograph for the same idea. TS consumers get that as a type
+ * error; everyone else gets it from `scripts/check-icons.mjs`.
+ *
+ * This module has no React import on purpose. The frontpage POCs are Astro (one Qwik)
+ * and cannot mount a React component just to draw a 16px glyph, so the string path is
+ * the primary API and `<Icon>` is a convenience on top of it.
+ */
+import { ICON_MARKUP } from './registry.generated'
+import type { IconName } from './registry.generated'
+
+export { ICON_MARKUP, ICON_NAMES, ICON_SOURCE_SLUGS, LUCIDE_VERSION } from './registry.generated'
+export type { IconName } from './registry.generated'
+
+/** The five accent families. Same set as the colour tokens — no icon-only families. */
+export const ICON_FAMILIES = ['primary', 'success', 'warning', 'danger', 'neutral'] as const
+export type IconFamily = (typeof ICON_FAMILIES)[number]
+
+/**
+ * How the icon is coloured. Every option resolves through theme tokens — there is
+ * no way to pass a raw colour — but WHICH treatment to use is the consumer's call.
+ *
+ * - `bare`   — glyph inherits `currentColor`. The default. Use it inside a button
+ *              or beside a label and the icon matches that text automatically, in
+ *              every theme, with no contrast obligation of its own.
+ * - `accent` — glyph painted `--color-<family>`. For when the icon is its own
+ *              element and should NOT match the surrounding text. You own the
+ *              contrast: a bare accent glyph clears 3:1 on a card/page surface in
+ *              28 of 36 theme/surface combinations for `warning`, so this is right
+ *              when you know the surface and wrong as a blanket default.
+ * - `tint`   — glyph in a `--color-<f>-bg` tile with `--color-on-<f>-bg` ink.
+ * - `filled` — glyph in a `--color-<f>` tile with `--color-on-<f>` ink.
+ *
+ * `tint` and `filled` clear 3:1 in all 18 themes for all five families.
+ */
+export type IconVariant = 'bare' | 'accent' | 'tint' | 'filled'
+
+export function isIconName(value: unknown): value is IconName {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(ICON_MARKUP, value)
+}
+
+const ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;'
+}
+
+/** Escape a caller-supplied string before it goes into the markup we return. */
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, c => ESCAPES[c])
+}
+
+export interface IconSvgOptions {
+  /** CSS length. Defaults to `1em` so the glyph scales with its surrounding text. */
+  size?: string | number
+  /** Extra classes appended after `hdk-icon`. */
+  className?: string
+  /**
+   * Paint the glyph with `--color-<family>` instead of inheriting `currentColor`.
+   * Adds `hdk-icon--<family>`; requires icons.css. Omit to inherit.
+   */
+  family?: IconFamily
+  /**
+   * Accessible name. Omit for decorative icons (the default) — those are rendered
+   * `aria-hidden` so a screen reader does not announce a glyph that repeats an
+   * adjacent label. Supply it only when the icon is the sole carrier of meaning.
+   */
+  title?: string
+  /** Stroke width in the 24x24 viewBox. Lucide's default is 2. */
+  strokeWidth?: number
+}
+
+/**
+ * A complete, standalone `<svg>` string for one icon.
+ *
+ * Astro/Qwik/plain HTML, no client JS:
+ *   <span set:html={getIconSvg('popcorn')} />
+ *   <span class="hdk-icon-tile hdk-icon-tile--tint hdk-icon-tile--warning"
+ *         set:html={getIconSvg('popcorn')} />
+ */
+export function getIconSvg(name: IconName, options: IconSvgOptions = {}): string {
+  const markup = ICON_MARKUP[name]
+  if (markup === undefined) {
+    // Loud rather than silent: a blank space where an icon should be is the failure
+    // mode that ships to production unnoticed.
+    throw new Error(
+      `getIconSvg: "${String(name)}" is not in the icon registry. ` +
+        `Add it to themes/src/icons/sources.json and run \`pnpm run generate:icons\`.`
+    )
+  }
+  const { size = '1em', className, title, strokeWidth = 2, family } = options
+  const dim = typeof size === 'number' ? `${size}px` : size
+  const cls = ['hdk-icon', family ? `hdk-icon--${family}` : '', className ?? '']
+    .filter(Boolean)
+    .join(' ')
+  const label = title
+    ? `role="img" aria-label="${escapeHtml(title)}"`
+    : 'aria-hidden="true" focusable="false"'
+
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" class="${escapeHtml(cls)}" ` +
+    `width="${escapeHtml(dim)}" height="${escapeHtml(dim)}" viewBox="0 0 24 24" ` +
+    `fill="none" stroke="currentColor" stroke-width="${strokeWidth}" ` +
+    `stroke-linecap="round" stroke-linejoin="round" ${label}>` +
+    (title ? `<title>${escapeHtml(title)}</title>` : '') +
+    markup +
+    '</svg>'
+  )
+}
+
+/** Class list for an accent tile, for the framework-free path. */
+export function getIconTileClass(
+  family: IconFamily = 'warning',
+  variant: Exclude<IconVariant, 'bare'> = 'tint',
+  round = false
+): string {
+  return (
+    `hdk-icon-tile hdk-icon-tile--${variant} hdk-icon-tile--${family}` +
+    (round ? ' hdk-icon-tile--round' : '')
+  )
+}
+
+// Canonical emoji -> icon name. Generated into registry.generated.ts from
+// emoji-map.json, so nothing loads JSON at runtime and there is one source.
+import { EMOJI_TO_ICON } from './registry.generated'
+
+export { EMOJI_TO_ICON } from './registry.generated'
+
+/** Variation selectors and skin tones are presentation, not identity. */
+function stripPresentation(s: string): string {
+  return [...s]
+    .filter(c => {
+      const p = c.codePointAt(0) ?? 0
+      return p !== 0xfe0f && p !== 0xfe0e && !(p >= 0x1f3fb && p <= 0x1f3ff)
+    })
+    .join('')
+}
+
+/**
+ * The registry name a raw emoji should become, or undefined if it has no
+ * canonical answer. `⚙` and `⚙️` resolve identically.
+ */
+export function emojiToIconName(emoji: string): IconName | undefined {
+  return EMOJI_TO_ICON[stripPresentation(emoji)] ?? EMOJI_TO_ICON[emoji]
+}