@placeholderco/placeholder-ui 1.0.11 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024
+Copyright (c) 2024-2026 PlaceholderUI Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,179 +1,183 @@
-# Placeholder UI
+# PlaceholderUI
 
-A modern, customizable Svelte 5 UI component library with comprehensive theming support via CSS variables.
+A Svelte 5 component library that you re-brand with a single config object.
+Forms, overlays, layout, data display, a TipTap rich-text editor and a
+CodeMirror code editor, all styled through one set of `--ui-*` CSS tokens.
 
-## Features
+- Svelte 5 runes, TypeScript, typed props on every component
+- Light / dark / system theme with persistence
+- Neutral default palette; swap in your own colours, font and logo in one call
+- 150+ icons exported as raw SVG strings
 
-- **70+ Components** - Buttons, forms, dialogs, tables, and more
-- **CSS Variable Theming** - Fully customizable via CSS custom properties
-- **Dark Mode** - Built-in light/dark theme support
-- **Svelte 5** - Built with modern Svelte 5 runes
-- **TypeScript** - Full TypeScript support
-- **Accessible** - Built with accessibility in mind
-- **Lightweight** - Built for simple DX with just enough flexibility
-
-## Installation
+## Install
 
 ```bash
-npm install @placeholderco/placeholder-ui
+pnpm add @placeholderco/placeholder-ui
 ```
 
-## Quick Start
+Peer dependency: `svelte ^5`.
+
+## Quick start
+
+Wrap your app in `AppShell` (it loads the base stylesheet and, by default,
+Bootstrap 5), then use components:
 
 ```svelte
-<script>
-  import { Button, Paper } from '@placeholderco/placeholder-ui';
+<script lang="ts">
+	import { AppShell, Navbar, Button } from '@placeholderco/placeholder-ui';
 </script>
 
-<Paper>
-  <h1>Hello World</h1>
-  <Button variant="primary">Click Me</Button>
-</Paper>
+<AppShell>
+	<Navbar appNav={{ href: '/', text: 'My App' }} />
+	<Button variant="primary">Save</Button>
+</AppShell>
 ```
 
-## Components
-
-### UI Components
-- `Button` - Buttons with multiple variants and sizes
-- `ActionIcon` - Icon buttons
-- `Badge` - Status badges
-- `Dialog` - Modal dialogs
-- `Drawer` - Slide-out panels
-- `Dropdown` - Dropdown menus
-- `Loader` - Loading spinners
-- `Pagination` - Page navigation
-- `Popover` - Floating content
-- `Table` - Data tables
-- `Tabs` - Tab navigation
-- `Tooltip` - Hover tooltips
-- `Toaster` - Toast notifications
-
-### Form Components
-- `Textbox` - Text input
-- `TextArea` - Multi-line text input
-- `Number` - Numeric input
-- `Select` / `SelectMulti` - Dropdowns
-- `Checkbox` - Checkboxes
-- `RadioGroup` - Radio buttons
-- `Switch` - Toggle switches
-- `DatePicker` / `TimePicker` / `DateTimePicker` - Date/time selection
-- `Autocomplete` - Autocomplete input
-- `Chips` - Tag input
-
-### Display Components
-- `Paper` - Card/panel container
-- `Alert` - Alert messages
-- `Avatar` - User avatars
-- `LinkCollection` - Link lists
-
-### Layout Components
-- `Navbar` - Navigation bar
-- `Sidenav` - Side navigation
-
-### Editors (separate package)
-
-For code and rich text editors, install the editors package:
+If you ship your own Bootstrap build or do not want Bootstrap at all, skip
+`AppShell` and import the token stylesheet yourself:
 
-```bash
-npm install @placeholderco/placeholder-ui-editors
+```ts
+import '@placeholderco/placeholder-ui/app.css';
 ```
 
-```svelte
-<script>
-  import { CodeMirror } from '@placeholderco/placeholder-ui-editors';
-</script>
+The bundled Bootstrap is also available on its own as `@placeholderco/placeholder-ui/bootstrap.css`.
 
-<CodeMirror bind:value={code} language="javascript" />
-```
+## Branding
 
-## Theming
+Everything colour- and font-related resolves to `--ui-*` custom properties, so
+there are two ways to brand the library.
 
-The library uses CSS variables for theming. Override variables after importing styles:
+### 1. A config object (recommended)
 
-```css
-:root {
-  /* Brand colors */
-  --pui-color-primary: #1a365d;
-  --pui-color-secondary: #48bb78;
-  --pui-color-accent: #4fd1c5;
+```ts
+// src/routes/+layout.svelte (or any startup code)
+import { applyTheme } from '@placeholderco/placeholder-ui';
+import logo from '$lib/logo.svg?raw';
 
-  /* Typography */
-  --pui-font-family-sans: 'Inter', sans-serif;
+applyTheme({
+	colors: {
+		primary: '#1e3a5f', // dark brand colour: solid buttons, headings
+		accent: '#93c5fd', // light brand colour: highlights, dark-mode accent
+		tertiary: '#a5f3fc' // supporting colour: links use its dark shade
+	},
+	fontFamily: "'Inter', system-ui, sans-serif",
+	logo // raw SVG, rendered by <Logo />
+});
+```
 
-  /* Spacing, radius, shadows, etc. */
-  --pui-radius-md: 8px;
-}
+Darker and lighter shades are derived automatically. Set `primaryDark`,
+`accentDark`, `tertiaryDark`, `tertiaryLight`, `link`, `linkHover` and the
+`*Contrast` text colours explicitly when you want full control.
+
+### Light and dark values
+
+Everything in the config is the light-mode value and also applies in dark mode.
+To change any of it while dark mode is active, add a `dark` block with the same
+shape. Only what you name is overridden; shades are derived per colour.
+
+```ts
+applyTheme({
+	colors: { primary: '#1e293b', accent: '#fbbf24', tertiary: '#7dd3fc' },
+	logo,
+	dark: {
+		colors: { accent: '#fde68a', link: '#fde68a' },
+		fontFamily: "'Inter', system-ui, sans-serif", // optional
+		logo: darkLogo // optional
+	}
+});
 ```
 
-### Dark Mode
+`applyTheme` injects one `<style>` element with a `:root` rule and a
+`:root.dark` rule, so values switch with the existing `.dark` class.
 
-Dark mode is activated by adding the `.dark` class to the document:
+To avoid a flash of the default palette on first paint, render the same config
+as CSS on the server:
 
-```javascript
-document.documentElement.classList.add('dark');
+```ts
+import { themeToCss } from '@placeholderco/placeholder-ui';
+const css = themeToCss(myTheme); // ":root { ... }\n:root.dark { ... }"
 ```
 
-Or use the built-in theme utilities:
+and place it in a `<style>` tag in `app.html` or your root layout head.
 
-```javascript
-import { setTheme } from '@placeholderco/placeholder-ui';
+### 2. Plain CSS
 
-setTheme('dark'); // 'light', 'dark', or 'system'
+Override the tokens in any stylesheet loaded after the library:
+
+```css
+:root {
+	--ui-primary-rgb: 30 58 95;
+	--ui-primary-rgbc: 30, 58, 95;
+	--ui-primary: rgb(var(--ui-primary-rgb));
+	--ui-primary-dark: #12253d;
+	--ui-accent-rgb: 147 197 253;
+	--ui-accent-rgbc: 147, 197, 253;
+	--ui-accent: rgb(var(--ui-accent-rgb));
+	--ui-accent-dark: #1d4ed8;
+	--ui-tertiary: #a5f3fc;
+	--ui-tertiary-dark: #0e7490;
+	--ui-font-family: 'Inter', system-ui, sans-serif;
+}
 ```
 
-## CSS Variable Reference
+The full token list, with comments on each role, is at the top of
+[src/lib/app.css](src/lib/app.css).
 
-### Primitives (tokens.css)
-- `--pui-color-*` - Color palette
-- `--pui-font-size-*` - Typography sizes
-- `--pui-spacing-*` - Spacing scale
-- `--pui-radius-*` - Border radius
-- `--pui-shadow-*` - Box shadows
+### Colour roles
 
-### Semantic (semantic.css)
-- `--pui-bg-*` - Background colors
-- `--pui-text-*` - Text colors
-- `--pui-border-*` - Border colors
+Keep these relationships when choosing colours, because components assume them:
 
-### Components (components.css)
-- `--pui-btn-*` - Button styles
-- `--pui-input-*` - Input styles
-- `--pui-paper-*` - Paper styles
-- And more per component...
+| Token           | Role                                                         |
+| --------------- | ------------------------------------------------------------ |
+| `--ui-primary`  | Dark. Solid buttons, active states, headings. White text.    |
+| `--ui-accent`   | Light. Hovers, highlights, the accent in dark mode.          |
+| `--ui-tertiary` | Light. Supporting fills; its `-dark` shade is used for links |
 
-## Icons
+### Fonts
 
-The library includes 145 SVG icons based on Tabler Icons:
+The library never bundles a font. Set `--ui-font-family` (or `fontFamily` in
+the config) and load the font yourself with `@font-face` or a `<link>`.
 
-```svelte
-<script>
-  import { Icon, iconCheck, iconX } from '@placeholderco/placeholder-ui';
-</script>
+### Logo
 
-<Icon svg={iconCheck} size="24px" />
-```
+`<Logo />` renders, in order of preference: its `svg` prop, the logo registered
+via `applyTheme({ logo })` / `setLogo()`, or a generic placeholder. Use
+`fill="currentColor"` in your SVG so it follows the theme, or register a separate
+dark-mode logo with `dark.logo` / `setLogo(light, dark)`.
 
-## Development
+## Variants
 
-```bash
-# Install dependencies
-npm install
+Button, Badge, ActionIcon, Dropdown, Accordion and ProgressBar share colour
+variants named after the tokens: `primary`, `accent`, `tertiary`, plus
+`-outline` and `-subtle` forms, and the neutral `secondary`, `white`, `danger`
+and `auto-*` variants.
 
-# Start dev server
-npm run dev
+## Theme (light / dark)
 
-# Type check
-npm run check
+```ts
+import { themeState, setTheme } from '@placeholderco/placeholder-ui';
 
-# Build
-npm run build
+setTheme('dark'); // 'light' | 'dark' | 'system'
+themeState.isDarkMode; // reactive boolean
+```
 
-# Run tests
-npm run test
+The `.light` / `.dark` class is applied to `<html>`. In your own components use
+`:global(.dark) .my-class { ... }` or the surface tokens (`--page-bg`,
+`--paper-body-bg`, `--text-color`, `--border-color`, ...).
+
+## Development
+
+```bash
+pnpm install
+pnpm run dev      # showcase app at http://localhost:5173
+pnpm run check    # svelte-check
+pnpm run build    # library + showcase
+pnpm run format
 ```
 
-## License
+`src/lib` is the published library; `src/routes` is the showcase. Every
+component has a demo page under `src/routes/components/<name>`.
 
-MIT License - see [LICENSE](LICENSE) for details.
+## License
 
-Icons derived from [Tabler Icons](https://tabler-icons.io/) (MIT License).
+[MIT](LICENSE)

package/dist/app.css

@@ -0,0 +1,178 @@
+/*
+ * PlaceholderUI design tokens
+ * ---------------------------
+ * Everything a consumer needs to re-brand the library lives in the `--ui-*`
+ * custom properties below. Override them in your own stylesheet, or call
+ * `applyTheme()` / `themeToCss()` from the package to generate them from a
+ * `ThemeConfig` object.
+ *
+ * Colour roles (keep these relationships when re-branding):
+ *   --ui-primary   dark brand colour. Used for solid buttons, headings, active
+ *                  states. Text on top of it uses --ui-primary-contrast.
+ *   --ui-accent    light brand colour. Used for highlights, hover states and as
+ *                  the adaptive accent in dark mode. Text on top of it uses
+ *                  --ui-accent-contrast.
+ *   --ui-tertiary  light supporting colour. Its *-dark shade is used for links
+ *                  and subtle text.
+ */
+
+:root {
+	/* ---- Typography ---- */
+	--ui-font-family:
+		ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif, 'Apple Color Emoji',
+		'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+
+	/* ---- Brand colours (neutral defaults) ---- */
+	--ui-primary-rgb: 30 58 95;
+	--ui-primary-rgbc: 30, 58, 95;
+	--ui-primary: rgb(var(--ui-primary-rgb));
+	--ui-primary-dark: #12253d;
+	--ui-primary-contrast: #ffffff;
+
+	--ui-accent-rgb: 147 197 253;
+	--ui-accent-rgbc: 147, 197, 253;
+	--ui-accent: rgb(var(--ui-accent-rgb));
+	--ui-accent-dark: #1d4ed8;
+	--ui-accent-contrast: var(--ui-primary);
+
+	--ui-tertiary-rgb: 165 243 252;
+	--ui-tertiary-rgbc: 165, 243, 252;
+	--ui-tertiary: rgb(var(--ui-tertiary-rgb));
+	--ui-tertiary-dark-rgbc: 14, 116, 144;
+	--ui-tertiary-dark: rgb(var(--ui-tertiary-dark-rgbc));
+	--ui-tertiary-light: #cffafe;
+
+	/* ---- Link colours ---- */
+	--ui-link-color: var(--ui-tertiary-dark);
+	--ui-link-hover-color: var(--ui-accent-dark);
+
+	/* ---- Legacy aliases (deprecated, kept for backwards compatibility) ---- */
+	--midnight-rgb: var(--ui-primary-rgb);
+	--midnight-rgbc: var(--ui-primary-rgbc);
+	--midnight: var(--ui-primary);
+	--pistachio-rgb: var(--ui-accent-rgb);
+	--pistachio-rgbc: var(--ui-accent-rgbc);
+	--pistachio: var(--ui-accent);
+	--pistachio-dark: var(--ui-accent-dark);
+	--turquoise: var(--ui-tertiary);
+	--turquoise-dark: var(--ui-tertiary-dark);
+
+	/* ---- Surfaces and text (light mode) ---- */
+	--off-white: rgb(221, 221, 221);
+	--input-bg: #fff;
+	--page-bg: #f1f3f5;
+	--text-color: #000;
+	--border-color: rgb(226, 232, 240);
+	--accent-color-rgb: var(--ui-primary-rgbc);
+	--accent-color: rgb(var(--accent-color-rgb));
+	--accent-text-color-rgb: 221, 221, 221;
+	--accent-text-color: rgb(221, 221, 221);
+	--paper-title-bg: rgb(252, 252, 252);
+	--paper-title-border: rgb(229, 231, 235);
+	--paper-body-bg: rgb(255, 255, 255);
+	--danger-bg: #e03131;
+	--danger-bg-hover: #c92a2a;
+	--danger-text: #ff5e5e;
+	--danger-bg-subtle: rgba(250, 82, 82, 0.12);
+
+	/* inputs */
+	--placeholder-color: rgb(161 161 170);
+	--input-bg-color: #fff;
+	--label-color: #6c757d;
+
+	/* layout */
+	--header-height: 46px;
+	--page-content-height: calc(100vh - var(--header-height));
+
+	--scrollbar-track: #fff;
+	--scrollbar-thumb: var(--ui-primary);
+
+	background-color: var(--page-bg);
+	color: var(--text-color);
+	font-family: var(--ui-font-family);
+}
+
+.dark {
+	--input-bg: rgb(33, 37, 41);
+	--page-bg: rgb(36, 37, 40);
+	--text-color: rgb(221, 221, 221);
+	--accent-color-rgb: var(--ui-accent-rgbc);
+	--border-color: rgb(55, 58, 64);
+	--accent-text-color-rgb: 221, 221, 221;
+	--accent-text-color: #000;
+	--paper-title-bg: rgb(18, 18, 18);
+	--paper-title-border: rgb(46, 46, 46);
+	--paper-body-bg: rgb(25, 26, 28);
+	--danger-text: #ffa8a8;
+	--danger-bg-subtle: rgba(250, 82, 82, 0.2);
+
+	/* inputs */
+	--placeholder-color: rgb(115 115 115);
+	--input-bg-color: rgb(33, 37, 41);
+	--label-color: rgb(141, 144, 149);
+
+	--scrollbar-track: #111;
+}
+
+body {
+	margin: 0;
+	font-family: var(--ui-font-family);
+}
+
+/* Form controls do not inherit fonts by default; make them follow the UI font
+   even when Bootstrap's reboot is not loaded. */
+button,
+input,
+select,
+textarea {
+	font-family: inherit;
+}
+
+header a {
+	text-decoration: none;
+	color: var(--ui-primary);
+	transition: color 200ms;
+}
+
+.dark header a {
+	color: white;
+}
+
+.dark header a:hover {
+	color: var(--ui-accent);
+}
+
+header .text-xl {
+	font-size: 1.25rem;
+	line-height: 1.75rem;
+}
+
+*::-webkit-scrollbar {
+	width: 19px;
+}
+
+*::-webkit-scrollbar-track {
+	background: var(--scrollbar-track);
+}
+
+*::-webkit-scrollbar-thumb {
+	background-color: var(--scrollbar-thumb);
+	border-radius: 10px;
+	border: 5px solid var(--scrollbar-track);
+}
+
+.vstack {
+	gap: 1rem;
+	display: flex;
+	flex-direction: column;
+}
+
+a {
+	color: var(--ui-link-color);
+	text-decoration: none;
+	transition: 200ms all;
+}
+
+a:hover {
+	color: var(--ui-link-hover-color);
+}