feather-k-demo-utils

feather-k-demo-utils

Shared demo utilities for Feather K Vue component demo repositories.

Purpose

feather-k-demo-utils centralizes common demo functionality used across feather-k- demo projects, including:

• Shared demo styles
• Shared demo UI components (such as DemoStats, DemoDebug, DemoDocs, and DemoSettings)
• Shared utility helpers (for example, CDN/version helpers)

This package is intended for internal/demo scenarios and consistency across Feather K demos, not as a general-purpose application UI library.

What's Included

• feather-k-demo-utils (root exports)
  • Demo components and top-level exports
• feather-k-demo-utils/components
  • Component-focused exports:
    • DemoStats: Demo stats footer
    • DemoCode: Collapsible code snippet with one-click copy to clipboard
    • DemoDebug: Collapsible debug panel (slot-based)
    • DemoDoc: Markdown file renderer for use inside DemoDocs
    • DemoDocHeader: Heading label for grouping DemoDoc entries inside DemoDocs
    • DemoDocs: Collapsible bottom viewport docs panel (slot-based)
    • DemoSettings: Collapsible settings panel (slot-based)
    • DemoNotes: Notes/info panel (slot-based)
    • DemoSelection: Demo selector dropdown (slot-based, enables switching between demos)
• feather-k-demo-utils/utils
  • Utility helpers used by demo apps
• feather-k-demo-utils/composables
  • useDemoStorage: reactive, scope-named local-storage state for demo settings
• feather-k-demo-utils/styles/demo.css
  • Demo-only stylesheet for shared demo layout and component styling

Quick Usage

Documentation

• Integration guide: DEMO-UTILS.md
• Component docs index: src/docs/README.md
• DemoCode: src/docs/DemoCode.md
• DemoDebug: src/docs/DemoDebug.md
• DemoDoc: src/docs/DemoDoc.md
• DemoDocHeader: src/docs/DemoDocHeader.md
• DemoDocs: src/docs/DemoDocs.md
• DemoNotes: src/docs/DemoNotes.md
• DemoSelection: src/docs/DemoSelection.md
• DemoSettings: src/docs/DemoSettings.md
• DemoStats: src/docs/DemoStats.md

Install:

npm install feather-k-demo-utils

Import demo styles once in your app entry:

import "feather-k-demo-utils/styles/demo.css";

Import what you need:

import { DemoStats, DemoDebug, DemoDoc, DemoDocs, DemoSettings, DemoNotes, DemoSelection, useDemoStorage } from "feather-k-demo-utils";
import { getFeatherkStylesVersionFromUrl } from "feather-k-demo-utils/utils";

DemoSelection

Dropdown selector for switching between multiple demos. Uses a slot to render the selected demo. Example:

<DemoSelection :options="demoOptions" v-model="selectedDemo">
	<template #default="{ selectedDemo }">
		<Demo1 v-if="selectedDemo === 'demo1'" />
		<Demo2 v-else-if="selectedDemo === 'demo2'" />
	</template>
</DemoSelection>

Where demoOptions is an array like:

const demoOptions = [
	{ text: "Demo 1", value: "demo1", status: "new" },
	{ text: "Demo 2", value: "demo2", status: "stable" },
];

By default, DemoSelection also keeps the selected demo in the URL query string using demo (for example, ?demo=demo2), and initializes selection from that query value when valid. Query matching is case-insensitive, so ?demo=DEMO2 and ?demo=demo2 both resolve.

Optional props:

• syncQueryParam?: boolean (default true) - Enable/disable URL query synchronization.
• queryParamName?: string (default "demo") - Change the query key used for sync.

DemoDebug

Collapsible debug panel. Slot content is only shown if provided.

<DemoDebug>
	<pre>{{ debugInfo }}</pre>
</DemoDebug>

DemoSettings

Collapsible settings panel. Slot content is only shown if provided.

<DemoSettings>
	<div>Settings content here</div>
</DemoSettings>

For persisted control values, use the reusable storage composable. DemoSettings provides the layout; it does not serialize its slot content.

const defaults = {
	showHeader: true,
	density: "Comfortable",
};

const { storageKey, state: settings, reset, isDefault } =
	useDemoStorage("feather-k-grid", "Basic", defaults);

Reset is supplied through the options prop. Pass storageKey directly to DemoSettings to show its built-in Clear button:

<DemoSettings
	:storage-key="storageKey"
	:options="{
		reset: { action: reset, disabled: isDefault },
	}"
>
	<!-- semantic settings controls -->
</DemoSettings>

DemoSettingsOptions is exported from both the package root and feather-k-demo-utils/components; it configures the optional Reset action. Clear is built into DemoSettings: it is disabled when the specified key is absent, invokes Reset when configured, then removes the key. useDemoStorage returns storageKey for this purpose. Its defaults are not written to local storage until the settings change.

Use settings.showHeader and settings.density in template bindings. When migrating an existing demo, move related individual refs into the defaults object and update the bindings to use this persisted settings object. Do not keep both refs and persisted properties as separate sources of truth.

DemoDocs and DemoDoc

Collapsible bottom viewport panel for one or more markdown documents. DemoDoc passes its src directly to zero-md, so use a hosted markdown URL such as jsDelivr or a file served from your app's public directory.

<DemoDocs label="Demo Docs" toggle-label="Toggle Demo Docs">
	<DemoDoc src="https://cdn.jsdelivr.net/npm/feather-k-demo-utils/src/docs/DemoDoc.md" />
	<DemoDoc src="/docs/local-demo-notes.md" />
</DemoDocs>

DemoNotes

Panel for displaying notes or additional information. Slot content is only shown if provided.

<DemoNotes>
	<h3>Notes</h3>
	<p>Some information about this demo.</p>
</DemoNotes>

For full integration steps (Vite env setup, stylesheet injection, and component usage), see DEMO-UTILS.md.

Publishing

Package publishing is handled via npm.

npm login
npm version patch   # or: npm version minor / npm version major
npm run build
git push
npm publish

npm version updates package.json and creates a git tag for the release version.

Consumer repository maintenance

The shared status, dependency-bump, deploy, and audit scripts are maintained in feather-k-tooling. Run them from that repository; each command requires an explicit --package. They continue to select sibling feather-k-* repos that declare the selected dependency and define a deploy script. See the tooling README for options, eligibility rules, and dry-run/write behavior.

Build-Time Publish Date

This package does not export an in-package PUBLISH_DATE. If a consuming demo needs publish date display, inject it at build time (for example via Vite define) in the consuming app.