@ekkolyth/ui 0.1.18 → 0.2.0

package/README.md

@@ -1,232 +1,121 @@
 # @ekkolyth/ui
 
-Shared UI component library, published as `@ekkolyth/ui`.
+Shared UI component library.
 
 ## Installation
 
 ```sh
-bun add @ekkolyth/ui
-```
-
-## Peer Dependencies
-
-- `react` ^19.2.0
-- `react-dom` ^19.2.0
-
-`next` is only reachable through the `/widget` compatibility entry
-(`Widget`). It ships as an ordinary workspace dependency here; the
-published package declares it as an **optional** peer so an app that never
-imports `/widget` never installs it.
-
-## Exports
-
-| Subpath | What it is |
-|---|---|
-| `.` | All UI components, hooks, and utilities. Theme runtime is not here — see `/themes/provider`. |
-| `./text` | `RichText` — renders Tiptap `JSONContent` through a node registry. |
-| `./layout` | `Container`. |
-| `./blocks` | `ColorPicker`, `Field`, `IconPicker`, `LoadingScreen`, `Widget`. |
-| `./hooks` | `useIsMobile`. |
-| `./themes/provider` | The framework-neutral theme runtime — see below. |
-| `./themes` | Stylesheet: all seven palettes, `@import`ed. |
-| `./themes/catpuccin/latte`, `./themes/catpuccin/frappe`, `./themes/catpuccin/macchiato`, `./themes/catpuccin/mocha`, `./themes/tokyo-night`, `./themes/ekko-os`, `./themes/ekkolyth` | Individual palette stylesheets — seven subpaths, one per palette. |
-| `./base.css` | The base theme layer — see "Base CSS" below. |
-
-`./widget` and `./convex` are **compatibility entries, not documented API.**
-They exist because specific `apps/web` call sites import from them and sit
-outside this package's edit surface; don't build new code against them.
-
-**Components:**
-Built on top of shadcn@latest.
-
-```tsx
-import { Button, Card, Dialog, useIsMobile, cn } from '@ekkolyth/ui'
-```
-
-## Theme Provider
-
-One framework-neutral provider, at `@ekkolyth/ui/themes/provider`. No
-`next-themes` — a vitest guard (`src/index.test.ts`) fails the build if
-anything reachable from the root barrel imports it. The subpath exports:
-
-```tsx
-import {
-    ThemeProvider,
-    ThemeScript,
-    ThemeSelect,
-    ThemeToggle,
-    Toaster,
-    useTheme,
-} from '@ekkolyth/ui/themes/provider'
-import type {
-    Appearance,
-    DarkThemes,
-    LightThemes,
-    ThemeContextState,
-    ThemeName,
-    ThemeProviderProps,
-    ThemeScriptProps,
-} from '@ekkolyth/ui/themes/provider'
-```
-
-**`ThemeProviderProps`:**
-- `defaultAppearance?: Appearance` — `"light" | "dark" | "system" | "normal"`, default `"system"`. `"normal"` is a legacy alias for `"light"`.
-- `lightTheme?: LightThemes | LightThemes[]` — light palette(s) to make available, default `"ekkolyth-light"`.
-- `darkTheme?: DarkThemes | DarkThemes[]` — dark palette(s) to make available, default `"ekkolyth-dark"`.
-- `storageKey?: string` — localStorage key prefix, default `"ekko-ui"`. Most apps won't need this; it matters if several frontends share a domain and need independent theme state.
-
-**`useTheme()` returns `ThemeContextState`:**
-- `appearance: Appearance` — the mode the user picked, before resolving `"system"`.
-- `resolvedMode: 'light' | 'dark'` — `appearance` resolved against `matchMedia` when it's `"system"`.
-- `resolvedTheme: ThemeName` — the palette currently applied for `resolvedMode`.
-- `availableThemes: { light: LightThemes[], dark: DarkThemes[] }`
-- `setAppearance: (appearance: Appearance) => void`
-- `setSpecificTheme: (mode: 'light' | 'dark', theme: LightThemes | DarkThemes) => void`
-
-`ThemeName` is the union of every palette (`LightThemes | DarkThemes`) —
-which palette is showing. `Appearance` is a separate concept — light/dark/system
-preference — deliberately a different word so the two don't get conflated at a
-call site.
-
-**`ThemeName` values:**
-- `"latte" | "ekkoos-light" | "ekkolyth-light"` — light palettes
-- `"mocha" | "frappe" | "macchiato" | "tokyo-night" | "ekkoos-dark" | "ekkolyth-dark"` — dark palettes
-
-### `ThemeScript`
-
-Renders a `<script>` that reads the stored appearance/palette from
-`localStorage` and sets `data-theme` + the `.dark` class on `<html>` before
-React hydrates. Put it in `<head>` — `app/layout.tsx` on Next.js,
-`__root.tsx` on TanStack Start — with the same `defaultAppearance`,
-`lightTheme`, `darkTheme`, and `storageKey` as the `<ThemeProvider>` it pairs
-with. Skipping it doesn't break anything, it just costs one painted frame of
-the wrong palette before the provider's own mount effect catches up.
-
-```tsx
-import { ThemeScript } from '@ekkolyth/ui/themes/provider'
-
-<head>
-  <ThemeScript defaultAppearance='system' />
-</head>
-```
-
-### Theme Toggle / Theme Select
-
-```tsx
-import { ThemeToggle, ThemeSelect } from '@ekkolyth/ui/themes/provider'
-```
-
-## Base CSS
-
-`@ekkolyth/ui/base.css` is the base theme layer — 34 color tokens with
-colourless (grayscale) defaults, the `@theme inline` mapping from those
-tokens into Tailwind utilities, `@custom-variant dark`, and an `@layer base`
-reset (`* { border-border outline-ring/50 }`, `body { bg-background
-text-foreground }`). Import it after the consuming app's own
-`@import 'tailwindcss'` and before its palette overrides:
-
-```css
-@import 'tailwindcss';
-@import '@ekkolyth/ui/base.css';
-/* app-specific palette overrides go here */
-```
-
-The export resolves to `./src/base.css`, not `./dist/base.css`, deliberately:
-`dist/` is gitignored, so a `dist` path would leave fresh clones and git
-worktrees unstyled until someone ran the UI package's build.
-
-## Theme Styles
-
-`@ekkolyth/ui/themes` is a **stylesheet entry** (a CSS `@import`, not a JS
-module) that pulls in all seven palettes. It stands in for the app's own
-Tailwind preamble, not the other way around — a theme picker that lets the
-user switch palettes needs every palette present, so import it alongside the
-three lines every consumer already writes:
-
-```css
-@import 'tailwindcss';
-@import 'tw-animate-css';
-@import '@ekkolyth/ui/base.css';
-@import '@ekkolyth/ui/themes';
-```
+# inside this monorepo
+"@ekkolyth/ui": "workspace:@ekkolyth/ui@*"
 
-Each palette is scoped to `html[data-theme='<name>']`; the provider and
-`ThemeScript` switch palettes by setting that attribute, so nothing here is a
-runtime import. Pull a single palette instead of the aggregate when an app
-only ever shows one:
-
-```css
-@import '@ekkolyth/ui/themes/catpuccin/latte';
-@import '@ekkolyth/ui/themes/tokyo-night';
-@import '@ekkolyth/ui/themes/ekkolyth';
+# anywhere else
+bun add @ekkolyth/ui
 ```
 
-## Usage Example
+App code MUST always import through its local package alias (`@ekkolyth/ui`),
+never via `@ekkolyth/ui/*`. The canonical name exists only so the consuming
+bundler can resolve package-internal references when transpiling source.
 
 ### Next.js Setup
 
 ```tsx
 // app/layout.tsx
-import { ThemeProvider, ThemeScript, Toaster } from '@ekkolyth/ui/themes/provider'
-import '@ekkolyth/ui/themes'
+import {
+  ThemeProvider,
+  ThemeScript,
+  Toaster,
+} from "@ekkolyth/ui/themes/provider";
+import "@ekkolyth/ui/themes";
 
 export default function RootLayout({ children }) {
   return (
     <html>
       <head>
-        <ThemeScript defaultAppearance='system' />
+        <ThemeScript defaultAppearance="system" />
       </head>
       <body>
         <ThemeProvider
-          defaultAppearance='system'
-          lightTheme={['latte', 'ekkolyth-light']}
-          darkTheme={['mocha', 'ekkolyth-dark']}
+          defaultAppearance="system"
+          lightTheme={["latte", "ekkolyth-light"]}
+          darkTheme={["mocha", "ekkolyth-dark"]}
         >
           {children}
           <Toaster />
         </ThemeProvider>
       </body>
     </html>
-  )
+  );
 }
 
 // app/page.tsx
-'use client'
-import { Button } from '@ekkolyth/ui'
-import { ThemeToggle, useTheme } from '@ekkolyth/ui/themes/provider'
+("use client");
+import { Button } from "@ekkolyth/ui";
+import { ThemeToggle, useTheme } from "@ekkolyth/ui/themes/provider";
 
 export default function Page() {
-  const { appearance, setAppearance } = useTheme()
+  const { appearance, setAppearance } = useTheme();
 
   return (
     <div>
       <ThemeToggle />
-      <Button onClick={() => setAppearance('dark')}>
-        Set Dark Mode
-      </Button>
+      <Button onClick={() => setAppearance("dark")}>Set Dark Mode</Button>
     </div>
-  )
+  );
 }
 ```
 
-## Release
+### TanStack Start Setup
 
-1. On the feature branch, describe the change: `bun run changeset`.
-2. Merge to `main`. `.github/workflows/release-packages.yml` consumes the
-   Changesets plan, bumps the manifest and changelog, builds the package, and
-   runs `scripts/stage-public.ts` to produce the `@ekkolyth/ui` artifact with its
-   curated `dist/` exports.
-3. `scripts/validate-package.ts` checks the staged tarball before anything
-   ships.
-4. The workflow publishes the validated tarball, commits the release state,
-   and tags the release `ui-v<version>`.
-
-A push to `main` with no pending changeset is a no-op — `changeset version`
-has nothing to consume, and the commit/publish steps detect the unchanged
-manifest and stop.
+```css
+/* src/styles.css */
+@import "tailwindcss";
+@import "@ekkolyth/ui/base.css";
+@import "@ekkolyth/ui/themes";
+```
 
-### Storybook + vitest
+```tsx
+// src/routes/__root.tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import {
+  ThemeProvider,
+  ThemeScript,
+  Toaster,
+} from "@ekkolyth/ui/themes/provider";
+import appCss from "../styles.css?url";
+
+export const Route = createRootRoute({
+  head: () => ({ links: [{ rel: "stylesheet", href: appCss }] }),
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return (
+    <html suppressHydrationWarning>
+      <head>
+        <HeadContent />
+        <ThemeScript defaultAppearance="system" />
+      </head>
+      <body>
+        <ThemeProvider
+          defaultAppearance="system"
+          lightTheme={["latte", "ekkolyth-light"]}
+          darkTheme={["mocha", "ekkolyth-dark"]}
+        >
+          <Outlet />
+          <Toaster />
+        </ThemeProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
 
-The package's storybook (`.storybook/main.ts`) and vitest (`vitest.config.ts`)
-configs include `@ekkolyth/ui` in their alias maps so stories and unit tests resolve
-internal imports the same way the dev/prod bundler does.
+`ThemeScript` goes in `<head>` with the same props as the `ThemeProvider` it
+pairs with — it applies the stored palette before first paint, so skipping it
+just costs one frame of the wrong theme.

package/dist/base.css

@@ -179,6 +179,10 @@
     }
 }
 
+.ts-chart-tooltip {
+    --ts-chart-tooltip-font: 500 1rem / 1.5 var(--font-sans);
+}
+
 .prose h1,
 .prose h2,
 .prose h3 {
@@ -231,7 +235,9 @@
 .prose thead th,
 .prose tbody td,
 .prose tfoot td {
+    /* biome-ignore lint/complexity/noImportantStyles: pinned by base.css.test.ts to beat the typography plugin */
     padding-top: 0.375rem !important;
+    /* biome-ignore lint/complexity/noImportantStyles: pinned by base.css.test.ts to beat the typography plugin */
     padding-bottom: 0.375rem !important;
     border-right: 1px solid color-mix(in oklab, var(--border) 40%, transparent);
 }

package/dist/blocks.d.ts

@@ -1,4 +1,4 @@
-import { i as ColorPicker, n as Field, r as validate, t as IconPicker } from "./index-DHF8OR1R.js";
+import { a as ComboboxField, i as Dropzone, n as Field, o as ComboboxFieldProps, r as validate, s as ColorPicker, t as IconPicker } from "./index-BJs5qfKG.js";
 import { n as LoadingScreenProps, t as LoadingScreen } from "./index-DsLGf2HX.js";
 import { n as WidgetLinkProps, r as WidgetProps, t as Widget } from "./index-qji4ohJZ.js";
-export { ColorPicker, Field, IconPicker, LoadingScreen, type LoadingScreenProps, Widget, type WidgetLinkProps, type WidgetProps, validate };
+export { ColorPicker, ComboboxField, type ComboboxFieldProps, Dropzone, Field, IconPicker, LoadingScreen, type LoadingScreenProps, Widget, type WidgetLinkProps, type WidgetProps, validate };

package/dist/blocks.js

@@ -1,4 +1,4 @@
-import { R as validate, d as Field, t as IconPicker, z as ColorPicker } from "./icon-picker-ByfHyJ7i.js";
-import { t as LoadingScreen } from "./loading-screen-DB3youyT.js";
+import { _ as validate, at as ColorPicker, b as ComboboxField, t as IconPicker, u as Field, v as Dropzone } from "./icon-picker-CwavOWKf.js";
+import { t as LoadingScreen } from "./loading-screen-DilmTJ3J.js";
 import { t as Widget } from "./widget-C2vjxQms.js";
-export { ColorPicker, Field, IconPicker, LoadingScreen, Widget, validate };
+export { ColorPicker, ComboboxField, Dropzone, Field, IconPicker, LoadingScreen, Widget, validate };

package/dist/convex.js

@@ -1,2 +1,2 @@
-import { t as LoadingScreen } from "./loading-screen-DB3youyT.js";
+import { t as LoadingScreen } from "./loading-screen-DilmTJ3J.js";
 export { LoadingScreen };

package/dist/hooks.d.ts

@@ -1,2 +1,2 @@
-import { t as useIsMobile } from "./use-mobile-BVGje-2e.js";
-export { useIsMobile };
+import { n as useIsMobile, t as useWindowScrollMargin } from "./use-window-scroll-margin-BeVjX6Le.js";
+export { useIsMobile, useWindowScrollMargin };

package/dist/hooks.js

@@ -1,2 +1,3 @@
-import { t as useIsMobile } from "./use-mobile-CqHXB_Nc.js";
-export { useIsMobile };
+import { t as useIsMobile } from "./use-mobile-C-Ak14Ip.js";
+import { t as useWindowScrollMargin } from "./use-window-scroll-margin-BQMpLEeT.js";
+export { useIsMobile, useWindowScrollMargin };