@kamod-ch/ui 0.2.1 → 1.1.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/kamod-ch/kamod-ui/main/.github/assets/logo-kamod-ui-dark.svg#gh-light-mode-only" alt="Kamod UI" width="162" />
-  <img src="https://raw.githubusercontent.com/kamod-ch/kamod-ui/main/.github/assets/logo-kamod-ui-light.svg#gh-dark-mode-only" alt="Kamod UI" width="162" />
+  <img src="https://raw.githubusercontent.com/kamod-ch/kamod-ui/main/.github/assets/logo-kamod-ui-dark.svg#gh-light-mode-only" alt="Kamod UI" width="280" />
+  <img src="https://raw.githubusercontent.com/kamod-ch/kamod-ui/main/.github/assets/logo-kamod-ui-light.svg#gh-dark-mode-only" alt="Kamod UI" width="280" />
 </p>
 
-<h1 align="center">Kamod UI</h1>
+# Kamod UI
 
 Lightweight UI components for **Preact** and **Tailwind**: composable primitives you can customize, extend, and ship without a heavy runtime. Open source; source is meant to be read and adapted.
 
@@ -16,6 +16,8 @@ Lightweight UI components for **Preact** and **Tailwind**: composable primitives
 
 **[Demo](https://ui.kamod.ch/)** · **[Component docs](https://ui.kamod.ch/docs/button)** · **[npm](https://www.npmjs.com/package/@kamod-ch/ui)** · **[GitHub](https://github.com/kamod-ch/kamod-ui)** · **[Issues](https://github.com/kamod-ch/kamod-ui/issues)**
 
+> Demo snippets in this repo use local aliases like `@/components/kamod-ui/*`. In your app, install `@kamod-ch/ui` and import from the package.
+
 > If Kamod UI saves you time, **[star the repo](https://github.com/kamod-ch/kamod-ui)** — it helps others discover the project.
 
 ![hero](https://raw.githubusercontent.com/kamod-ch/kamod-ui/main/.github/assets/kitchen-sink.png)
@@ -44,21 +46,104 @@ Many UI kits are heavier than necessary, overly opinionated, or tied to React. K
 
 ## Quick start
 
+### Vite + Preact + Tailwind v4 starter
+
 ```bash
-pnpm add @kamod-ch/ui preact @preact/signals tailwindcss
+pnpm create vite@latest my-app -- --template preact-ts
+cd my-app
+pnpm add @kamod-ch/ui @preact/signals
+pnpm add -D tailwindcss @tailwindcss/vite
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import preact from "@preact/preset-vite";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [preact(), tailwindcss()],
+});
 ```
 
 ```css
-/* app.css */
+/* src/app.css */
 @import "tailwindcss";
 @import "@kamod-ch/ui/theme.css";
+
+:root {
+  font-family: Inter, system-ui, sans-serif;
+}
+```
+
+```tsx
+// src/main.tsx
+import { render } from "preact";
+import { App } from "./app";
+import "./app.css";
+
+render(<App />, document.getElementById("app")!);
 ```
 
 ```tsx
+// src/app.tsx
 import { Button } from "@kamod-ch/ui";
 
 export function App() {
-  return <Button>Click me</Button>;
+  return (
+    <main class="p-6">
+      <Button>Click me</Button>
+    </main>
+  );
+}
+```
+
+This is the smallest full setup. If you already have a Vite app, keep the `@kamod-ch/ui/theme.css` import and add `@kamod-ch/ui` + `@preact/signals`.
+
+Browse the [live component docs](https://ui.kamod.ch/docs/button) for variants, composition, and RTL examples.
+
+## Troubleshooting (Tailwind v4)
+
+### Components look unstyled
+
+Make sure your global CSS imports both files, in this order:
+
+```css
+@import "tailwindcss";
+@import "@kamod-ch/ui/theme.css";
+```
+
+If `theme.css` is missing, Kamod's component classes and semantic tokens will not compile.
+
+### Tailwind works in CSS but utility classes are missing in Vite
+
+If you're using Vite, make sure the Tailwind v4 plugin is installed and enabled:
+
+```ts
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+});
+```
+
+Without the plugin, Vite may not process the Tailwind v4 import pipeline correctly.
+
+### You're on Tailwind v3
+
+Kamod UI requires Tailwind CSS v4. Tailwind v3 does not support the import-based setup used here.
+
+### Theme overrides do not apply
+
+Override CSS variables after importing `theme.css`, not before it:
+
+```css
+@import "tailwindcss";
+@import "@kamod-ch/ui/theme.css";
+
+:root {
+  --primary: var(--color-fuchsia-700);
+  --radius: 0.75rem;
 }
 ```
 
@@ -80,7 +165,7 @@ Browse the [live component docs](https://ui.kamod.ch/docs/button) for variants,
 pnpm add @kamod-ch/ui preact @preact/signals
 ```
 
-The published library on npm is **[`@kamod-ch/ui`](https://www.npmjs.com/package/@kamod-ch/ui)**. This monorepo root and `apps/demo` are not published. The former package [`@kamod-ui/core`](https://www.npmjs.com/package/@kamod-ui/core) and the unscoped [`kamod-ui`](https://www.npmjs.com/package/kamod-ui) name are legacy — install `@kamod-ch/ui` instead.
+The published library on npm is **[`@kamod-ch/ui`](https://www.npmjs.com/package/@kamod-ch/ui)**. This monorepo root and `packages/docs` are not published. The former package [`@kamod-ui/core`](https://www.npmjs.com/package/@kamod-ui/core) and the unscoped [`kamod-ui`](https://www.npmjs.com/package/kamod-ui) name are legacy — install `@kamod-ch/ui` instead.
 
 Import the default theme once so Tailwind compiles component classes and semantic CSS tokens:
 
@@ -97,11 +182,11 @@ Import the default theme once so Tailwind compiles component classes and semanti
 
 **Import signals yourself** when you use Kamod's lower-level helpers:
 
-| Use case                            | Import                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------- |
+| Use case                            | Import                                                                         |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
 | Custom controlled primitives        | `@kamod-ch/ui/lib/signals` → `createControllableSignal`                        |
 | Overlay dismiss / roving focus      | `@kamod-ch/ui/lib/interactive` → `createDismissableLayer`, `createRovingFocus` |
-| Advanced toast / sonner integration | `@kamod-ch/ui/toast` or `@kamod-ch/ui/sonner` stores                         |
+| Advanced toast / sonner integration | `@kamod-ch/ui/toast` or `@kamod-ch/ui/sonner` stores                           |
 
 See the [**Signals** column in the component reference](https://github.com/kamod-ch/kamod-ui/blob/main/.docs/COMPONENTS.md) for which exports use signals internally (direct, indirect via Dialog/Popover, or none).
 
@@ -114,6 +199,8 @@ import { Button } from "@kamod-ch/ui"; // root barrel
 import { Button } from "@kamod-ch/ui/button"; // per-component subpath
 ```
 
+The demo docs in `packages/docs` rewrite the same examples to local aliases like `@/components/kamod-ui/button`. That alias only exists inside the demo app; in your app, install `@kamod-ch/ui` and import from the package.
+
 The package ships a minimal `sideEffects` list (progress indeterminate keyframes and CSS only), so modern bundlers tree-shake the root barrel reliably.
 
 ### Component sizes
@@ -146,7 +233,7 @@ Override semantic tokens after importing the default theme:
 }
 ```
 
-For full control, copy from [`packages/core/src/theme.css`](https://github.com/kamod-ch/kamod-ui/blob/main/packages/core/src/theme.css) or see the demo's [`foundation.css`](https://github.com/kamod-ch/kamod-ui/blob/main/apps/demo/src/styles/foundation.css) and [`themes.css`](https://github.com/kamod-ch/kamod-ui/blob/main/apps/demo/src/styles/themes.css).
+For full control, copy from [`packages/core/src/theme.css`](https://github.com/kamod-ch/kamod-ui/blob/main/packages/core/src/theme.css) or see the demo's [`foundation.css`](https://github.com/kamod-ch/kamod-ui/blob/main/packages/docs/src/styles/foundation.css) and [`themes.css`](https://github.com/kamod-ch/kamod-ui/blob/main/packages/docs/src/styles/themes.css).
 
 ## Documentation
 
@@ -165,13 +252,13 @@ Open the URL printed in the terminal for the kitchen sink and component docs. Qu
 
 ## Contributing
 
-| Workspace        | Path             | Role                                     |
-| ---------------- | ---------------- | ---------------------------------------- |
-| `@kamod-ch/ui` | `packages/core/` | Published library (65 component exports) |
-| `demo`           | `apps/demo/`     | Kitchen sink + interactive docs          |
+| Workspace           | Path             | Role                                     |
+| ------------------- | ---------------- | ---------------------------------------- |
+| `@kamod-ch/ui`      | `packages/core/` | Published library (65 component exports) |
+| `@kamod-ch/ui-docs` | `packages/docs/` | Kitchen sink + interactive docs          |
 
 - Open issues for bugs and ideas; PRs welcome for components, docs, and examples.
-- Key scripts: `pnpm dev`, `pnpm check`, `pnpm fmt`, `pnpm lint`, `pnpm docs:components`
+- Key scripts: `pnpm dev`, `pnpm check`, `pnpm format`, `pnpm lint`, `pnpm docs:components`
 - Tooling details: [`.docs/interna.md`](https://github.com/kamod-ch/kamod-ui/blob/main/.docs/interna.md)
 
 Maintainers: see [`.docs/MAINTAINERS.md`](https://github.com/kamod-ch/kamod-ui/blob/main/.docs/MAINTAINERS.md) for npm release workflow.

package/dist/{AlertDialog-ALB541qy.d.ts → AlertDialog-GadhKjPC.d.ts}

@@ -3,7 +3,7 @@ import { ComponentChildren, JSX } from 'preact';
 import { VariantProps } from 'tailwind-variants';
 import { b as button } from './Button-vQnkiVTI.js';
 import { e as DialogCloseProps, d as DialogTriggerProps, c as DialogProps } from './Dialog-BOIteLfe.js';
-import { b as DialogContentProps } from './DialogContent-CK1t4m4e.js';
+import { b as DialogContentProps } from './DialogContent-cQHSRQdT.js';
 
 type AlertDialogActionProps = DialogCloseProps & {
     variant?: VariantProps<typeof button>["variant"];

package/dist/{DialogContent-CK1t4m4e.d.ts → DialogContent-cQHSRQdT.d.ts}

@@ -19,6 +19,6 @@ type DialogContentProps = JSX.HTMLAttributes<HTMLDivElement> & {
  * - **modal (default):** Backdrop + centered panel; use `class` only for sizing (e.g. `sm:max-w-sm`).
  * - **slot:** Single root node — **required** for legacy/custom layouts that already implement `fixed inset-0` overlay + inner card (otherwise you stack two modals).
  */
-declare const DialogContent: ({ forceMount, presentation, showCloseButton, class: className, children, onKeyDown, "data-slot": dataSlot, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: DialogContentProps) => preact.VNode<any> | null;
+declare const DialogContent: ({ forceMount, presentation, showCloseButton, class: className, children, onKeyDown, "data-slot": dataSlot, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: DialogContentProps) => JSX.Element | preact.VNode<{}> | null;
 
 export { DialogContent as D, type DialogContentPresentation as a, type DialogContentProps as b };

package/dist/{Drawer-B3pZMn5j.d.ts → Drawer-CdjXZxxK.d.ts}

@@ -2,7 +2,7 @@ import * as preact from 'preact';
 import { ComponentChildren } from 'preact';
 import { e as DialogCloseProps, d as DialogTriggerProps } from './Dialog-BOIteLfe.js';
 import { c as DialogDescriptionProps, b as DialogTitleProps } from './DialogTitle-CerJD0oA.js';
-import { g as SheetFooterProps, f as SheetHeaderProps, e as SheetContentProps, d as SheetProps } from './Sheet-s0xRF22F.js';
+import { g as SheetFooterProps, f as SheetHeaderProps, e as SheetContentProps, d as SheetProps } from './Sheet-DZ-p-aHY.js';
 
 type DrawerCloseProps = DialogCloseProps;
 declare const DrawerClose: (props: DrawerCloseProps) => preact.JSX.Element;

package/dist/{Sheet-s0xRF22F.d.ts → Sheet-DZ-p-aHY.d.ts}

@@ -19,7 +19,7 @@ type SheetContentProps = JSX.HTMLAttributes<HTMLDivElement> & {
     children?: ComponentChildren;
     "data-slot"?: string;
 };
-declare const SheetContent: ({ side, showCloseButton, children, class: className, forceMount, "data-slot": dataSlot, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: SheetContentProps) => preact.VNode<any> | null;
+declare const SheetContent: ({ side, showCloseButton, children, class: className, forceMount, "data-slot": dataSlot, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: SheetContentProps) => JSX.Element | preact.VNode<{}> | null;
 
 type SheetProps = DialogProps & {
     children?: ComponentChildren;

package/dist/SidebarProvider-Bx7-BdQn.d.ts

@@ -0,0 +1,160 @@
+import * as tailwind_variants from 'tailwind-variants';
+import { VariantProps } from 'tailwind-variants';
+import { JSX, ComponentChildren } from 'preact';
+import { a as InputProps } from './Input-Cem05el9.js';
+import { a as SeparatorProps } from './Separator-DCQYrnpB.js';
+
+type SidebarMenuProps = JSX.HTMLAttributes<HTMLUListElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarMenu: ({ class: className, children, ...rest }: SidebarMenuProps) => JSX.Element;
+type SidebarMenuItemProps = JSX.HTMLAttributes<HTMLLIElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarMenuItem: ({ class: className, children, ...rest }: SidebarMenuItemProps) => JSX.Element;
+declare const sidebarMenuButton: tailwind_variants.TVReturnType<{
+    variant: {
+        default: string;
+        outline: string;
+    };
+    size: {
+        default: string;
+        sm: string;
+        lg: string;
+    };
+}, undefined, string[], {
+    variant: {
+        default: string;
+        outline: string;
+    };
+    size: {
+        default: string;
+        sm: string;
+        lg: string;
+    };
+}, undefined, tailwind_variants.TVReturnType<{
+    variant: {
+        default: string;
+        outline: string;
+    };
+    size: {
+        default: string;
+        sm: string;
+        lg: string;
+    };
+}, undefined, string[], unknown, unknown, undefined>>;
+type SidebarMenuButtonProps = JSX.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof sidebarMenuButton> & {
+    asChild?: boolean;
+    isActive?: boolean;
+    tooltip?: string | JSX.HTMLAttributes<HTMLDivElement>;
+    children?: ComponentChildren;
+};
+declare const SidebarMenuButton: ({ asChild, isActive, variant, size, tooltip, class: className, children, ...rest }: SidebarMenuButtonProps) => JSX.Element;
+type SidebarMenuActionProps = JSX.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+    showOnHover?: boolean;
+    children?: ComponentChildren;
+};
+declare const SidebarMenuAction: ({ class: className, asChild, showOnHover, children, ...rest }: SidebarMenuActionProps) => JSX.Element;
+type SidebarMenuBadgeProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarMenuBadge: ({ class: className, children, ...rest }: SidebarMenuBadgeProps) => JSX.Element;
+type SidebarMenuSkeletonProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    showIcon?: boolean;
+};
+declare const SidebarMenuSkeleton: ({ class: className, showIcon, ...rest }: SidebarMenuSkeletonProps) => JSX.Element;
+type SidebarMenuSubProps = JSX.HTMLAttributes<HTMLUListElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarMenuSub: ({ class: className, children, ...rest }: SidebarMenuSubProps) => JSX.Element;
+type SidebarMenuSubItemProps = JSX.HTMLAttributes<HTMLLIElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarMenuSubItem: ({ class: className, children, ...rest }: SidebarMenuSubItemProps) => JSX.Element;
+type SidebarMenuSubButtonProps = JSX.AnchorHTMLAttributes<HTMLAnchorElement> & {
+    asChild?: boolean;
+    size?: "sm" | "md";
+    isActive?: boolean;
+    children?: ComponentChildren;
+};
+declare const SidebarMenuSubButton: ({ asChild, size, isActive, class: className, children, ...rest }: SidebarMenuSubButtonProps) => JSX.Element;
+
+type SidebarInputProps = InputProps;
+declare const SidebarInput: ({ class: className, ...rest }: SidebarInputProps) => JSX.Element;
+type SidebarSeparatorProps = SeparatorProps;
+declare const SidebarSeparator: ({ class: className, ...rest }: SidebarSeparatorProps) => JSX.Element;
+type SidebarGroupProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarGroup: ({ class: className, children, ...rest }: SidebarGroupProps) => JSX.Element;
+type SidebarGroupLabelProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+    children?: ComponentChildren;
+};
+declare const SidebarGroupLabel: ({ class: className, asChild, children, ...rest }: SidebarGroupLabelProps) => JSX.Element;
+type SidebarGroupActionProps = JSX.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+    children?: ComponentChildren;
+};
+declare const SidebarGroupAction: ({ class: className, asChild, children, ...rest }: SidebarGroupActionProps) => JSX.Element;
+type SidebarGroupContentProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarGroupContent: ({ class: className, children, ...rest }: SidebarGroupContentProps) => JSX.Element;
+
+type SidebarRailProps = JSX.ButtonHTMLAttributes<HTMLButtonElement>;
+declare const SidebarRail: ({ class: className, ...rest }: SidebarRailProps) => JSX.Element;
+
+type SidebarInsetProps = JSX.HTMLAttributes<HTMLElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarInset: ({ class: className, children, ...rest }: SidebarInsetProps) => JSX.Element;
+
+type SidebarFooterProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarFooter: ({ class: className, children, ...rest }: SidebarFooterProps) => JSX.Element;
+
+type SidebarContentProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarContent: ({ class: className, children, ...rest }: SidebarContentProps) => JSX.Element;
+
+type SidebarHeaderProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    children?: ComponentChildren;
+};
+declare const SidebarHeader: ({ class: className, children, ...rest }: SidebarHeaderProps) => JSX.Element;
+
+type SidebarTriggerProps = Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "size"> & {
+    class?: string;
+};
+declare const SidebarTrigger: ({ class: className, onClick, ...rest }: SidebarTriggerProps) => JSX.Element;
+
+type SidebarProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    side?: "left" | "right";
+    variant?: "sidebar" | "floating" | "inset";
+    collapsible?: "offcanvas" | "icon" | "none";
+    children?: ComponentChildren;
+};
+declare const Sidebar: ({ side, variant, collapsible, class: className, children, ...rest }: SidebarProps) => JSX.Element;
+
+type SidebarContextValue = {
+    state: "expanded" | "collapsed";
+    open: boolean;
+    setOpen: (open: boolean | ((prev: boolean) => boolean)) => void;
+    openMobile: boolean;
+    setOpenMobile: (open: boolean | ((prev: boolean) => boolean)) => void;
+    isMobile: boolean;
+    toggleSidebar: () => void;
+};
+declare const useSidebar: () => SidebarContextValue;
+type SidebarProviderProps = JSX.HTMLAttributes<HTMLDivElement> & {
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children?: ComponentChildren;
+};
+declare const SidebarProvider: ({ defaultOpen, open: openProp, onOpenChange: setOpenProp, class: className, style, children, ...rest }: SidebarProviderProps) => JSX.Element;
+
+export { type SidebarHeaderProps as A, type SidebarContentProps as B, type SidebarFooterProps as C, type SidebarInsetProps as D, type SidebarRailProps as E, type SidebarGroupProps as F, type SidebarMenuProps as G, Sidebar as S, SidebarContent as a, SidebarFooter as b, SidebarGroup as c, SidebarGroupAction as d, SidebarGroupContent as e, SidebarGroupLabel as f, SidebarHeader as g, SidebarInput as h, SidebarInset as i, SidebarMenu as j, SidebarMenuAction as k, SidebarMenuBadge as l, SidebarMenuButton as m, SidebarMenuItem as n, SidebarMenuSkeleton as o, SidebarMenuSub as p, SidebarMenuSubButton as q, SidebarMenuSubItem as r, type SidebarProps as s, SidebarProvider as t, type SidebarProviderProps as u, SidebarRail as v, SidebarSeparator as w, SidebarTrigger as x, useSidebar as y, type SidebarTriggerProps as z };