@ekanos/ui 0.1.1 → 0.1.2

package/README.md

@@ -21,6 +21,8 @@ One subpath per component, mirroring the `@kit/ui` names:
 | `@ekanos/ui/select`          | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, …                                    |
 | `@ekanos/ui/form`            | `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField` |
 | `@ekanos/ui/input`           | `Input`                                                                                                       |
+| `@ekanos/ui/textarea`        | `Textarea`                                                                                                    |
+| `@ekanos/ui/switch`          | `Switch`                                                                                                      |
 | `@ekanos/ui/dropdown-menu`   | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, …                           |
 | `@ekanos/ui/label`           | `Label`                                                                                                       |
 | `@ekanos/ui/skeleton`        | `Skeleton`                                                                                                    |
@@ -45,23 +47,157 @@ implementations here are original, and `pack:test` fails the build if any
 `packages/ui/src/makerkit` source is ever inlined into `dist/`. Inside the
 monorepo, first-party code keeps using `@kit/ui` as before.
 
-## Styling: this package ships NO CSS
+## Styling
 
-Components emit Tailwind class strings referencing Fusion's **semantic design
-tokens** (`bg-primary`, `text-muted-foreground`, `border-border`, …). They
-render correctly only inside a host that owns that CSS — the Fusion app or the
-integration dev harness. Nothing here reads or requires the host's
-`theme-tokens.ts` runtime; the contract is purely "the host page loads
-Fusion's stylesheet".
+Every component emits Tailwind class strings bound to Fusion's semantic design
+tokens (`bg-primary`, `text-muted-foreground`, `border-border`, `shadow-card`,
+…), so something has to define those. This package ships that CSS.
 
-Two host-provided assets to know about:
+Pick **one** of the two paths. Loading both means two copies of every utility.
 
-- **Tailwind tokens**: the host defines the semantic token variables and
-  utilities. Without them the components render unstyled HTML.
-- **Icons are Font Awesome**: `Icon` renders `<i class="fa-solid fa-house">`
-  styled by the Font Awesome Pro web-font CSS the host loads. Legacy PascalCase
-  Lucide names are translated to FA equivalents via a bundled map; there is no
-  `lucide-react` at runtime.
+### You do NOT use Tailwind — import the compiled stylesheet
+
+```ts
+import '@ekanos/ui/styles.css';
+```
+
+Self-contained: Tailwind's Preflight, the design tokens, light and dark, and
+every utility class the components in this package emit — all pre-compiled.
+Nothing else to install, no build step, no config. Works in Next.js, Vite, CRA,
+a plain `<link rel="stylesheet">`, anything.
+
+### You DO use Tailwind v4 — import the preset
+
+```css
+@import 'tailwindcss';
+@import '@ekanos/ui/theme.css';
+```
+
+That registers the token map (`--color-primary` → `--primary`, the `--radius-*`
+scale, `shadow-card`), the token values for both themes, the base rules, the
+`dark:` variant, and an `@source` pointing at this package's bundles so your
+Tailwind build generates the components' utilities itself. You then get the
+Fusion tokens in **your own** class strings too.
+
+Also published, if you want the pieces separately: `@ekanos/ui/tokens.css`
+(just the custom properties, no Tailwind at-rules) and `@ekanos/ui/base.css`
+(the base rules).
+
+### What `styles.css` does and does not contain
+
+It contains the utilities **this package's components** emit — derived by
+compiling every class string found in the built bundles. It is not a copy of
+Tailwind.
+
+So `<Button>` and `<Card>` render correctly, but a Tailwind class *you* write in
+*your* component (`p-8`, `grid-cols-3`, `h-5 w-5`) has no rule in it and will do
+nothing. That is inherent: a pre-compiled stylesheet cannot know class names
+that don't exist yet. Two options, both fine:
+
+- style your own markup with plain CSS or inline styles, or
+- take the Tailwind path above, which is how Fusion itself works.
+
+`styles.css` includes Tailwind's Preflight, which is a global reset — it will
+normalise margins, headings and form controls across your whole page. If that
+is unwelcome, use the Tailwind path and control layering yourself.
+
+### Page background and dark mode
+
+The stylesheet will not repaint your page uninvited. To adopt Fusion's page
+surface — which is what makes dark mode look right rather than dark cards
+floating on a white page — add the opt-in class:
+
+```html
+<body class="ekanos-root">
+```
+
+Dark mode resolves in three states, in this order:
+
+| State                                     | Result                       |
+| ----------------------------------------- | ---------------------------- |
+| nothing set                               | light                        |
+| `@media (prefers-color-scheme: dark)`     | dark                         |
+| `.dark` or `[data-theme='dark']` ancestor | dark, beating the media query |
+| `.light` or `[data-theme='light']` on `:root` | light, beating the media query |
+
+So a partner app with no theme toggle at all still follows the OS, and one with
+a toggle (next-themes, or your own) works by setting the class. Fusion itself is
+class-only; the media query is added here for apps that have no switcher.
+
+### Tokens: exactly the ones the components use
+
+`tokens.css` is not a copy of Fusion's `shadcn-ui.css`. It carries the 25
+semantic colour tokens the published components actually reference, plus their
+paired foregrounds, `--radius`, and the one elevation level any of them uses
+(`--el-card`, behind `shadow-card`). Fusion's chart, sidebar and assistant
+tokens, and nine of its ten elevation levels, are deliberately absent.
+
+The build enforces this in both directions: it re-compiles the same class
+strings against Fusion's **full** token map and fails if a component has started
+using a token this package doesn't ship (which would otherwise emit no CSS at
+all, silently). See `scripts/build-css.mjs`.
+
+### Fonts
+
+Fusion pairs **Figtree** (body) with **Bricolage Grotesque** (headings) and
+loads them via `next/font`. This package only names them in `--font-sans` /
+`--font-heading`, followed by a system fallback stack — no webfont is bundled or
+fetched. For exact typographic parity, load them yourself:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Figtree:wght@300..700&family=Bricolage+Grotesque:wght@200..800&display=swap"
+/>
+```
+
+Without them, everything still renders — in your platform's UI font.
+
+### Icons: you must supply Font Awesome
+
+`Icon` renders Font Awesome markup (`<i class="fa-solid fa-house">`) and this
+package ships **no icon font**, because Fusion uses **Font Awesome Pro** (7.2.0,
+© Fonticons, Inc.) under a commercial licence. Redistributing it inside an MIT
+package would hand reuse rights we do not hold to everyone who installs this;
+`pack:test` fails the build if any font data ever reaches `dist/`.
+
+**If you hold a Font Awesome Pro licence**, load your own Pro CSS (or kit) and
+every icon renders exactly as it does in Fusion.
+
+**If you do not**, use Font Awesome Free — but read this, because the fit is
+imperfect:
+
+```sh
+npm install @fortawesome/fontawesome-free
+```
+
+```ts
+import '@fortawesome/fontawesome-free/css/all.min.css';
+```
+
+Free ships `fa-solid`, `fa-regular` and `fa-brands`. It has **no `fa-light` or
+`fa-duotone` family**, and it is missing many Pro glyphs — and `fa-light` is
+exactly what `@kit/ui`'s resolver falls back to for an icon name it doesn't
+recognise. Force everything into a family Free actually has:
+
+```tsx
+import { IconStyleOverrideProvider } from '@ekanos/ui/icon';
+
+<IconStyleOverrideProvider value="solid">{children}</IconStyleOverrideProvider>;
+```
+
+Any glyph Free still doesn't have falls back to a question mark rather than
+vanishing (`--ekanos-icon-fa-fallback`, default `'\f059'`).
+
+**If you load no Font Awesome at all**, icons do not disappear silently: this
+package's CSS draws a placeholder box (`□`) in their place, so "I forgot the
+icon font" is visibly different from "my code is broken". Change or disable it
+with `--ekanos-icon-fallback`.
+
+Note that FA glyphs are sized by `font-size`, not box dimensions, and `Icon`
+derives that from the first `h-*` / `w-*` / `size-*` token in `className` in JS
+— so `<Icon className="h-5 w-5" />` is the right *visual* size even on the
+no-Tailwind path where those utilities have no CSS rule.
 
 ## Runtime notes
 
@@ -110,14 +246,37 @@ runtime is a declared dependency of this package.
 ## Building / verifying
 
 ```bash
-pnpm --filter @ekanos/ui build      # tsup → dist/ (ESM + .d.ts per subpath)
+pnpm --filter @ekanos/ui build      # tsup → dist/, then scripts/build-css.mjs → the stylesheets
 pnpm --filter @ekanos/ui pack:test  # clean-room publish gate (see scripts/pack-test.mjs)
 ```
 
+The build runs in two stages, in this order for a reason: `tsup` bundles the
+components, then `scripts/build-css.mjs` scans the *built* `dist/*.js` for class
+strings and compiles exactly those through Tailwind. Deriving the utility set
+from the build output rather than a hand-kept list is what makes it impossible
+to add a component whose classes have no CSS.
+
+That script carries three fatal gates:
+
+- **dangling** — every `var(--x)` the token map reaches for must be defined.
+- **coverage** — the same class strings are re-compiled against Fusion's full
+  token map, and the build fails if a component has begun using a token this
+  package doesn't ship. Without this, such a utility would just silently emit
+  nothing.
+- **lockstep** — `tokens.css` spells its dark values out twice (a media query
+  and an explicit selector, because CSS can't share a block between them); both
+  must stay in agreement.
+
 `pack:test` packs the tarball, asserts dist-only contents, fails on any
 `@kit/` leak, asserts `'use client'` preservation, then installs the tarball
 into a temp project outside the workspace and typechecks
 (`skipLibCheck: false`) + esbuild-bundles a consumer importing every subpath.
 
+It also gates the stylesheets: all four must ship, clear a size floor, still
+contain known utilities and both theme states, resolve through esbuild as
+`@ekanos/ui/styles.css`, and carry **no** icon-font data — `@font-face`, a
+webfont reference or a glyph table in `dist/` fails the build, for the same
+licensing reason the Makerkit lineage check exists.
+
 `prepack` runs the build, so a publish can never ship a stale or missing
 `dist/`.

package/dist/base.css

@@ -0,0 +1,116 @@
+/*
+ * @ekanos/ui — base rules the components depend on
+ * ------------------------------------------------------------------
+ * Plain CSS. Everything here is something a component's class strings assume
+ * about the page rather than state themselves. Kept deliberately short: a
+ * library stylesheet has no business restyling a host's page.
+ */
+
+/*
+ * Default border colour.
+ *
+ * Tailwind's Preflight resets every element to `border: 0 solid`, which leaves
+ * `border-color` at `currentColor`. Several components then set only a border
+ * *width* and expect the theme colour: `Button variant="outline"` and
+ * `SelectTrigger` use a bare `border`, `Badge` uses `border border-transparent`.
+ * Without this rule those borders come out the colour of the label text.
+ *
+ * This is the same rule Fusion's own `@layer base` carries
+ * (apps/web/styles/globals.css).
+ */
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  border-color: var(--border, currentColor);
+}
+
+/*
+ * Missing-icon placeholders.
+ *
+ * `@ekanos/ui/icon` renders Font Awesome markup — `<i class="fa-solid fa-house">`
+ * — and this package ships NO icon font. Fusion uses Font Awesome **Pro**,
+ * which is commercially licensed and cannot be redistributed inside an MIT
+ * package. See the README for what to load instead.
+ *
+ * That leaves two ways for an icon to come out blank, and both are silent, so
+ * there are two placeholders. Neither can change the rendering of a correctly
+ * licensed Pro host.
+ */
+
+/*
+ * 1. No Font Awesome CSS at all. An `<i>` then has no content and no box, so
+ *    icons render as *literally nothing* and a partner cannot tell "I forgot
+ *    the icon font" apart from "my code is broken". This draws a placeholder
+ *    box instead.
+ *
+ *    `:where()` keeps the specificity at (0,0,1) — below Font Awesome's own
+ *    `:is(…)::before` at (0,1,1) — so FA wins `content` outright the instant
+ *    any Font Awesome stylesheet is present.
+ *
+ *    BUT specificity only settles properties BOTH rules declare, and `content`
+ *    is the ONLY one FA sets on `::before`. FA declares `font-family` and
+ *    `font-weight` on the ELEMENT (`.fa-solid { font-family: var(--_fa-family) }`),
+ *    never on the pseudo-element. So declaring them here left them uncontested
+ *    at `::before` level — a declared value beats an inherited one regardless
+ *    of specificity — and FA's correct codepoint got painted in system-ui,
+ *    which has no glyph in the Private Use Area. The result was Chromium's
+ *    missing-glyph hex box on every icon in any app that loads both this
+ *    stylesheet and a real Font Awesome build.
+ *
+ *    So this rule must NOT set the font. Inheriting is correct in both cases:
+ *    with FA present the element carries the FA family and the glyph resolves;
+ *    with FA absent the element inherits the body font, which does have U+25A1.
+ *
+ *    Override the glyph with `--ekanos-icon-fallback` (any CSS <string>), or
+ *    switch it off with `--ekanos-icon-fallback: ''`.
+ */
+:where(i[class*='fa-']) {
+  display: inline-block;
+  font-style: normal;
+  line-height: 1;
+  text-align: center;
+}
+
+:where(i[class*='fa-'])::before {
+  content: var(--ekanos-icon-fallback, '\25a1');
+  font-style: normal;
+}
+
+/*
+ * 2. Font Awesome Free IS loaded, but the requested glyph is Pro-only. Free
+ *    covers `fa-solid` / `fa-regular` / `fa-brands`; it has no `fa-light` or
+ *    `fa-duotone` families and is missing many Pro glyphs — including
+ *    `fa-light fa-shapes`, which is what this package's icon resolver falls
+ *    back to for an unmapped name. Font Awesome drives its glyphs off a per-icon
+ *    `--fa` custom property (`.fa-house { --fa: '\f015' }`) and renders
+ *    `content: var(--fa)`, so a glyph Free doesn't define leaves `--fa` unset
+ *    and `content` invalid — nothing renders, again silently.
+ *
+ *    Giving `--fa` a zero-specificity default fixes that: any real Font Awesome
+ *    icon class is (0,1,0) and beats it, so known glyphs are untouched, while
+ *    an unknown one falls through to a question mark (`\f059`,
+ *    `fa-circle-question`, which Free does ship). Matches the fallback the
+ *    Fusion dev harness uses against Font Awesome Free.
+ */
+:where(i[class*='fa-']) {
+  --fa: var(--ekanos-icon-fa-fallback, '\f059');
+}
+
+/*
+ * Opt-in page shell.
+ *
+ * Fusion's app sets `bg-background text-foreground` on `<body>`; this package
+ * will not do that to a host page uninvited. Put `class="ekanos-root"` on
+ * `<body>` (or on any wrapper around Ekanos UI) to adopt Fusion's page surface
+ * — which is what makes dark mode look right, rather than dark cards floating
+ * on a white page.
+ */
+.ekanos-root {
+  background-color: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}