@octans/ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarwin Stroh-Spijer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+<img src="./octans-logo.svg" alt="" width="72" height="72" align="left" hspace="12" />
+
+# Octans UI
+
+A Vue 3 component library — friendly, accessible, themeable UI primitives and application
+shell components.
+
+<br clear="left" />
+
+[octans.dev](https://octans.dev) — live Storybook docs ·
+[github.com/tarwin/octans-ui](https://github.com/tarwin/octans-ui) ·
+[Issues](https://github.com/tarwin/octans-ui/issues)
+
+## Install
+
+```sh
+pnpm add @octans/ui
+```
+
+`vue` is a peer dependency. `vue-router` is an optional peer — you only need it
+if you use the components that render router links (`MaybeRouterLink`,
+`UnstyledLink`, and anything that accepts a `to` prop).
+
+## Usage
+
+```ts
+import { createApp } from 'vue'
+import Octans from '@octans/ui'
+import '@octans/ui/style.css'
+
+import App from './App.vue'
+
+createApp(App).use(Octans).mount('#app')
+```
+
+Components can also be imported individually without installing the plugin:
+
+```vue
+<script setup lang="ts">
+import { Button, Card } from '@octans/ui'
+</script>
+
+<template>
+  <Card title="Hello">
+    <Button primary>Click me</Button>
+  </Card>
+</template>
+```
+
+Installing the plugin additionally registers the `$ui` and `$t` globals, which
+give you the imperative APIs (`$ui.toast`, `$ui.confirm`, `$ui.format`, …) from
+inside templates.
+
+Most components that manage overlays expect a `<UiProvider>` at the root of your
+app, so tooltips can share a single delay group:
+
+```vue
+<template>
+  <UiProvider>
+    <RouterView />
+  </UiProvider>
+</template>
+```
+
+## Translations
+
+Every user-facing string resolves through a small built-in dictionary. English
+ships with the library and is always the fallback, so a missing key degrades to
+readable English rather than a raw dotted key.
+
+```ts
+import { addTranslations, setTranslationLocale } from '@octans/ui'
+
+addTranslations('fr', {
+  'ui.modal.close': 'Fermer',
+  'ui.modal.cancel': 'Annuler'
+})
+setTranslationLocale('fr')
+```
+
+Or supply them when installing the plugin:
+
+```ts
+app.use(Octans, {
+  locale: 'fr',
+  translations: { fr: { 'ui.modal.close': 'Fermer' } }
+})
+```
+
+Strings support `{placeholder}` interpolation. Unknown placeholders are left
+in place rather than rendering `undefined`, so gaps are visible.
+
+## Icons
+
+Icons resolve through [Iconify](https://iconify.design). **Every icon the
+library uses internally is pre-bundled**, so components render offline with no
+network request and no icon font to install.
+
+Names you pass yourself resolve through `api.iconify.design` at runtime. That
+needs no build step, but it is a round trip on first use and renders nothing at
+all offline. To bundle exactly the icons your app uses, run this before a build
+and commit the result:
+
+```sh
+npx octans-icons        # scans ./src, writes src/octansIcons.ts
+```
+
+```ts
+import './octansIcons' // once, at startup
+```
+
+It finds Iconify names in your source, fetches only those, and generates a file
+that registers them. Re-run it when you add an icon; `npx octans-icons --help`
+lists the options. Names your code builds at runtime (`` `mdi:${name}` ``) can't
+be seen by a source scan and keep resolving through the API.
+
+To bundle a whole collection instead — simpler, but `@iconify-json/lucide` is
+roughly 1.5 MB against a typical app's few kB of actual icons:
+
+```ts
+import { addCollection } from '@octans/ui'
+import icons from '@iconify-json/lucide/icons.json'
+
+addCollection(icons)
+```
+
+Font Awesome class strings (`fa fa-plus`) are still accepted for compatibility,
+but the library no longer uses or ships Font Awesome — load it yourself if you
+pass those names.
+
+## Theming
+
+Colours, radii and shadows are CSS custom properties, so themes swap at runtime:
+
+```ts
+import { setTheme, persistTheme } from '@octans/ui'
+
+setTheme('dark') // 'light' | 'dark' | 'system'
+persistTheme() // optional: remember the choice across reloads
+```
+
+To rebrand, generate a theme from seed colours — every ramp and semantic token
+follows, dark mode included:
+
+```ts
+import { createTheme, applyCustomTheme } from '@octans/ui'
+
+applyCustomTheme(createTheme({ name: 'Ocean', primary: '#0f9d8f' }))
+```
+
+Or override any semantic token directly:
+
+```css
+:root {
+  --octans-primary: #0f9d8f;
+  --octans-radius-field: 0; /* square controls */
+}
+```
+
+See the **Design Tokens** and **Theme Builder** pages in Storybook for the full
+token list and an interactive editor.
+
+## Development
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow — the short
+version:
+
+```sh
+pnpm install
+pnpm dev            # Storybook on :6006
+```
+
+| Script            | Does                                             |
+| ----------------- | ------------------------------------------------ |
+| `pnpm dev`        | Storybook dev server                             |
+| `pnpm build-lib`  | Build the ES + UMD bundles and type declarations |
+| `pnpm type-check` | `vue-tsc --noEmit`                               |
+| `pnpm lint`       | ESLint                                           |
+| `pnpm format`     | Prettier                                         |
+| `pnpm verify`     | lint + type-check + build                        |
+
+## Conventions
+
+### Import public components by directory
+
+Especially when one public component imports another.
+
+```ts
+// ✅ Good
+import { Button } from '@/components/Button'
+
+// ❌ Unnecessarily longer
+import { Button } from '@/components/Button/Button.vue'
+
+// ❌ We can't easily search for '@/components/' to find references
+import { Button } from '../Button'
+
+// ❌ Creates a dependency on ALL components
+import { Button } from '@/components/index.ts'
+```
+
+### Order SFC sections consistently
+
+`<script>`, then `<template>`, then `<style>` — per the
+[official Vue recommendation](https://vuejs.org/style-guide/rules-recommended.html#single-file-component-top-level-element-order).
+
+### Name component types predictably
+
+Each component exports an interface defining its public props, named
+`<Component>Props`. Supporting types start with the component name and end in
+`Type`:
+
+```ts
+export interface SelectProps {
+  options: SelectOptionType[]
+}
+
+export interface SelectOptionType {
+  value: string
+  label: string
+}
+```
+
+## License
+
+[MIT](./LICENSE)

package/bin/octans-icons.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+//
+// octans-icons — bundle the Iconify icons your app actually uses.
+//
+// @octans/ui ships only the icons the library itself renders. Anything else you
+// pass to `<Icon icon="...">` is fetched from api.iconify.design on first use.
+// That is a fine default — you get all 200k+ icons with no build step — but it
+// means a network round trip per collection, nothing at all offline, and a
+// third-party dependency at runtime.
+//
+// This scans your source for Iconify names, fetches just those, and writes a
+// file you import once at startup. Run it before a build; commit the output.
+//
+//   npx octans-icons                     # scans ./src, writes src/octansIcons.ts
+//   npx octans-icons app --out app/icons.ts
+//   npx octans-icons --dry-run           # list what it finds, write nothing
+//
+// Deliberately standalone — no imports from the rest of the package, so it
+// keeps working regardless of what the library's own build is doing.
+
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, extname, join, relative, resolve } from 'node:path'
+
+const HELP = `octans-icons — bundle the Iconify icons your app uses
+
+Usage
+  npx octans-icons [dir...] [options]
+
+Options
+  --out <file>   Where to write the bundle. Default: <first dir>/octansIcons.ts
+                 A .js extension emits JavaScript instead of TypeScript.
+  --dry-run      Print the icons found and exit without writing.
+  --quiet        Only print errors.
+  -h, --help     Show this.
+
+Then import it once, before anything renders:
+
+  import './octansIcons'
+
+Re-run it whenever you add an icon. Names built at runtime (\`\\\`mdi:\${name}\\\`\`)
+can't be seen by a source scan — those keep resolving through the API, which
+still works. Pass them explicitly by putting the literal names in an array.
+`
+
+const args = process.argv.slice(2)
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(HELP)
+  process.exit(0)
+}
+
+const takeFlag = (name) => {
+  const index = args.indexOf(name)
+  if (index === -1) return undefined
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('-')) {
+    console.error(`octans-icons: ${name} needs a value`)
+    process.exit(1)
+  }
+  args.splice(index, 2)
+  return value
+}
+
+const outFlag = takeFlag('--out')
+const dryRun = args.includes('--dry-run')
+const quiet = args.includes('--quiet')
+const dirs = args.filter((arg) => !arg.startsWith('-'))
+const roots = dirs.length ? dirs : ['src']
+const outFile = resolve(outFlag ?? join(roots[0], 'octansIcons.ts'))
+
+const say = (message) => {
+  if (!quiet) console.log(message)
+}
+
+const SCANNABLE = /\.(vue|ts|tsx|js|jsx|mjs|cjs|svelte|astro|html)$/
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage'])
+
+const walk = async (dir) => {
+  const files = []
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    console.error(`octans-icons: cannot read ${dir}`)
+    process.exit(1)
+  }
+  for (const entry of entries) {
+    if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...(await walk(path)))
+    else if (SCANNABLE.test(entry.name)) files.push(path)
+  }
+  return files
+}
+
+// A name in a comment is documentation, not usage. Line-level on purpose: it
+// drops whole comment lines rather than trying to parse a trailing `//` out of
+// a line that may well contain one inside a string.
+const isCommentLine = (line) => {
+  const trimmed = line.trimStart()
+  return ['*', '//', '/*', '<!--'].some((marker) => trimmed.startsWith(marker))
+}
+
+// Any quoted `prefix:name` is a candidate. `prefix` alone is far too loose —
+// "height:100vh" and "grid:1 / 3" have the same shape — so candidates are kept
+// only if the prefix is a real Iconify collection, which the API can tell us.
+const CANDIDATE =
+  /["'`](?:not:)?([a-z0-9]+(?:-[a-z0-9]+)*):([a-z0-9]+(?:-[a-z0-9]+)*)["'`]/g
+
+const fetchJson = async (url) => {
+  let response
+  try {
+    response = await fetch(url)
+  } catch (error) {
+    console.error(
+      `octans-icons: could not reach api.iconify.design — ${error.message}`
+    )
+    process.exit(1)
+  }
+  if (!response.ok) {
+    console.error(
+      `octans-icons: ${url} — ${response.status} ${response.statusText}`
+    )
+    process.exit(1)
+  }
+  return response.json()
+}
+
+const files = (await Promise.all(roots.map((dir) => walk(dir)))).flat()
+if (!files.length) {
+  console.error(`octans-icons: no source files under ${roots.join(', ')}`)
+  process.exit(1)
+}
+
+const candidates = new Map()
+for (const file of files) {
+  if (resolve(file) === outFile) continue
+  const source = await readFile(file, 'utf8')
+  for (const line of source.split('\n')) {
+    if (isCommentLine(line)) continue
+    for (const [, prefix, icon] of line.matchAll(CANDIDATE)) {
+      if (!candidates.has(prefix)) candidates.set(prefix, new Set())
+      candidates.get(prefix).add(icon)
+    }
+  }
+}
+
+say(`Scanned ${files.length} files in ${roots.join(', ')}`)
+
+const collectionList = await fetchJson('https://api.iconify.design/collections')
+const known = [...candidates].filter(([prefix]) => prefix in collectionList)
+
+if (!known.length) {
+  console.error('octans-icons: no Iconify names found — nothing to bundle.')
+  process.exit(1)
+}
+
+const collections = []
+const skipped = []
+for (const [prefix, icons] of known.sort()) {
+  const names = [...icons].sort()
+  const data = await fetchJson(
+    `https://api.iconify.design/${prefix}.json?icons=${names.join(',')}`
+  )
+  // A miss is not fatal here: the candidate pattern is greedy by design, so an
+  // unknown name is as likely to be a false positive as a typo. Those keep
+  // working through the API, so warn and carry on rather than break a build.
+  for (const name of names) {
+    if (!data.icons?.[name]) skipped.push(`${prefix}:${name}`)
+  }
+  if (data.icons && Object.keys(data.icons).length) {
+    collections.push(data)
+    say(`  ${prefix}: ${Object.keys(data.icons).sort().join(', ')}`)
+  }
+}
+
+const total = collections.reduce((n, c) => n + Object.keys(c.icons).length, 0)
+if (skipped.length) {
+  console.warn(
+    `\noctans-icons: not in Iconify, left to resolve at runtime — ${skipped.join(', ')}`
+  )
+}
+
+if (dryRun) {
+  say(`\n${total} icons found. Nothing written (--dry-run).`)
+  process.exit(0)
+}
+
+const isTs = extname(outFile) === '.ts'
+const contents = `// GENERATED by \`npx octans-icons\` — do not edit by hand.
+//
+// Iconify data for every icon name found in this project's source, so they
+// render instantly and offline instead of being fetched from the Iconify API.
+// Import this once at startup, before anything renders.
+//
+// Re-run \`npx octans-icons\` after adding an icon.
+import { addCollection } from '@octans/ui'
+
+const collections = ${JSON.stringify(collections, null, 2)}
+
+collections.forEach((collection) => addCollection(collection${isTs ? ' as any' : ''}))
+`
+
+await writeFile(outFile, contents)
+say(
+  `\nWrote ${relative(process.cwd(), outFile)} — ${total} icons in ` +
+    `${collections.length} collection(s).\n\nImport it once at startup:\n` +
+    `  import './${relative(dirname(outFile), outFile).replace(/\.(ts|js)$/, '')}'`
+)

package/dist/components/ActionList/ActionList.vue.d.ts

@@ -0,0 +1,77 @@
+import { PopperPlacementType } from '../Popper';
+import { ActionTooltipPositionType } from '../types';
+export interface ActionListProps {
+    /**
+     * A single list of actions to render.
+     */
+    items?: ActionListItemType[];
+    /**
+     * Groups of actions to render.
+     */
+    sections?: ActionListSectionType[];
+    placement?: PopperPlacementType;
+    disabled?: boolean;
+    /**
+     * Custom z-index for the popper.
+     */
+    zIndex?: number;
+    /**
+     * Open sub-menus on hover instead of click. Propagates to all nested levels.
+     */
+    autoOpen?: boolean;
+    /**
+     * Internal: makes this list's own trigger open on hover. Set by the parent
+     * menu when `autoOpen` is enabled; not meant to be set directly.
+     */
+    hoverTrigger?: boolean;
+}
+export interface ActionListItemType {
+    label: string;
+    icon?: string | null;
+    /**
+     * Secondary text shown beneath the label.
+     */
+    helpText?: string;
+    disabled?: boolean;
+    url?: string;
+    external?: boolean;
+    /**
+     * Tooltip to show when hovering the item.
+     */
+    tooltip?: string;
+    /**
+     * Tooltip position, "top", "bottom", "right" or "left".
+     */
+    tooltipPosition?: ActionTooltipPositionType;
+    onAction?(): void;
+    items?: ActionListItemType[];
+    sections?: ActionListSectionType[];
+}
+export interface ActionListSectionType {
+    items: ActionListItemType[];
+    title?: string;
+}
+declare var __VLS_19: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_19) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<ActionListProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    show: () => any;
+    hide: () => any;
+    close: () => any;
+}, string, import('vue').PublicProps, Readonly<ActionListProps> & Readonly<{
+    onShow?: (() => any) | undefined;
+    onHide?: (() => any) | undefined;
+    onClose?: (() => any) | undefined;
+}>, {
+    placement: PopperPlacementType;
+    items: ActionListItemType[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/ActionList/ActionListButton.vue.d.ts

@@ -0,0 +1,85 @@
+import { PropType, VNode } from 'vue';
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+    };
+    helpText: {
+        type: StringConstructor;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Tooltip to show when hovering the button.
+     */
+    tooltip: {
+        type: StringConstructor;
+    };
+    /**
+     * Tooltip position, "top", "bottom", "right" or "left".
+     */
+    tooltipPosition: {
+        type: StringConstructor;
+        default: string;
+    };
+    dropdown: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    url: {
+        type: StringConstructor;
+    };
+    external: {
+        type: BooleanConstructor;
+    };
+    icon: {
+        type: PropType<string | null>;
+    };
+}>, () => VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    label: {
+        type: StringConstructor;
+    };
+    helpText: {
+        type: StringConstructor;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Tooltip to show when hovering the button.
+     */
+    tooltip: {
+        type: StringConstructor;
+    };
+    /**
+     * Tooltip position, "top", "bottom", "right" or "left".
+     */
+    tooltipPosition: {
+        type: StringConstructor;
+        default: string;
+    };
+    dropdown: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    url: {
+        type: StringConstructor;
+    };
+    external: {
+        type: BooleanConstructor;
+    };
+    icon: {
+        type: PropType<string | null>;
+    };
+}>> & Readonly<{}>, {
+    disabled: boolean;
+    tooltipPosition: string;
+    external: boolean;
+    dropdown: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/components/ActionList/ActionListMenu.vue.d.ts

@@ -0,0 +1,18 @@
+import { ActionListItemType, ActionListSectionType } from './ActionList.vue';
+export interface ActionListMenuProps {
+    items?: ActionListItemType[];
+    sections?: ActionListSectionType[];
+    /**
+     * Open sub-menus on hover instead of click. Propagates to nested levels.
+     */
+    autoOpen?: boolean;
+}
+declare const __VLS_export: import('vue').DefineComponent<ActionListMenuProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    close: () => any;
+}, string, import('vue').PublicProps, Readonly<ActionListMenuProps> & Readonly<{
+    onClose?: (() => any) | undefined;
+}>, {
+    items: ActionListItemType[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/ActionList/index.d.ts

@@ -0,0 +1 @@
+export { default as ActionList, type ActionListProps, type ActionListItemType, type ActionListSectionType } from './ActionList.vue';

package/dist/components/AppFrame/AppFrame.vue.d.ts

@@ -0,0 +1,26 @@
+import { AppFrameProps } from './types';
+declare var __VLS_8: {}, __VLS_10: {}, __VLS_38: {}, __VLS_40: {};
+type __VLS_Slots = {} & {
+    sidebar?: (props: typeof __VLS_8) => any;
+} & {
+    topbar?: (props: typeof __VLS_10) => any;
+} & {
+    default?: (props: typeof __VLS_38) => any;
+} & {
+    footer?: (props: typeof __VLS_40) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<AppFrameProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<AppFrameProps> & Readonly<{}>, {
+    loading: boolean;
+    layout: import('./types').AppFrameLayoutType;
+    layoutMode: import('../GlobalNav').GlobalNavLayoutModeType;
+    sidebarMin: boolean;
+    sidebarCollapse: import('./types').AppFrameSidebarCollapseType;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};