feather-k-demo-utils 0.0.48 → 0.1.1

package/DEMO-UTILS.md

@@ -156,54 +156,135 @@ import { DemoSettings } from "feather-k-demo-utils";
 }
 ```
 
-### Demo Layout Structure (required for consistent utility styles)
+
+### Demo Layout Structure
+
+#### App.vue (Root Level)
+
+The root layout begins with a single `.demo-app` wrapper. This is the top-level container for all demo content and navigation. DemoStats is typically rendered at this level, after the demo selection and main content.
 
 ```html
-<!-- App.vue top level "demo-app" -->
+<!-- App.vue -->
 <div class="demo-app">
-  <!-- each demo (if there are multiple)-->
-  <div class="featherk-demo">
-    <form class="demo-form">
-      <!-- one or more .fk-field-block rows -->
-
-      <div class="demo-actions">
-        <!-- action buttons (Clear / Submit, etc.) -->
-      </div>
-    </form>
-
-    <div class="demo-notes">
-      <!-- notes content -->
-    </div>
+  <div class="fk-field-block demo-selection">
+    <!-- Demo selection UI (DropDownList, Label, etc.) -->
+  </div>
+  <h1>Grid Exploration</h1>
+  <div>
+    <!-- Demo component is conditionally rendered here -->
+    <BasicGrid v-if="selectedDemo === 'Basic'" />
+    <RowNavGrid v-if="selectedDemo === 'RowNavigation'" />
+    <!-- ...other demo components... -->
   </div>
+  <DemoStats
+    v-if="stylesVersion"
+    :version="stylesVersion"
+    :publishDate="publishDate"
+    :active="false"
+  />
+  <!-- Optionally, DemoNotes can also be used at this level -->
 </div>
-
-Keep this aligned with whichever demo-utils release you want to display.
 ```
 
-### Required Demo Shell Structure
+**Where the layout begins and ends:**
+- `.demo-app` starts at the top of App.vue and wraps all demo navigation, content, and stats.
+- Each demo component (e.g., BasicGrid.vue) is rendered inside `.demo-app` but outside of `.fk-field-block.demo-selection`.
+
+#### Demo Component Level (e.g., BasicGrid.vue, RowNavGrid.vue)
 
-All demo components must use the following structure for consistent styling:
+Each individual demo component must begin with a `.featherk-demo` wrapper. This ensures consistent styling and utility support. DemoSettings, DemoDebug, and DemoNotes are most often used at this level.
 
 ```html
-<div class="demo-app">
-  <div class="featherk-demo">
-    <form class="demo-form">
-      <div class="fk-field-block">
-        <!-- Field content here -->
-      </div>
-      <div class="demo-actions">
-        <!-- Action buttons here -->
-      </div>
-    </form>
-    <div class="demo-notes">
-      <!-- Notes content here -->
-    </div>
+<!-- BasicGrid.vue, RowNavGrid.vue, etc. -->
+<div class="featherk-demo">
+  <h1>Demo Title</h1>
+  <div class="demo-form">
+    <!-- Demo form content, grid, etc. -->
   </div>
+  <DemoNotes>
+    <!-- Notes specific to this demo -->
+  </DemoNotes>
+  <DemoSettings>
+    <!-- Optional: settings panel for this demo -->
+  </DemoSettings>
+  <DemoDebug>
+    <!-- Optional: debug panel for this demo -->
+  </DemoDebug>
 </div>
 ```
 
+**Where the layout begins and ends:**
+- `.featherk-demo` starts at the top of each demo component and wraps all demo-specific content, including forms, notes, settings, and debug panels.
+
+**Component Placement Guidelines:**
+- `DemoStats`: Typically rendered at the App.vue (`.demo-app`) level, after the main demo content.
+- `DemoNotes`: Can be used at both the App.vue and demo component level for contextual notes.
+- `DemoSettings` and `DemoDebug`: Most often used inside each demo component, after the main demo content.
+
 **Always use these class names and hierarchy in your demo components.**
-This ensures demo-utils styles and features work as intended.
+This ensures demo-utils styles and features work as intended and matches the feather-k-grid project structure.
+
+
+# Multi-Demo Navigation with DemoSelection
+
+For projects with multiple demos, use the `DemoSelection` component from `feather-k-demo-utils` to provide a consistent, accessible demo picker and slot-based rendering for your demo components.
+
+**Important:** Always import `DemoSelection` from `feather-k-demo-utils`. Do not use a local `DemoSelection.vue` file. The package provides the official, up-to-date version.
+
+## DemoSelection Component
+
+`DemoSelection` encapsulates a Kendo UI for Vue DropDownList and exposes the selected value to its slot, allowing you to conditionally render demo components in a clean, reusable way.
+
+### Props
+- `options: Array<{ text: string; value: string }>` — List of demo options to display in the DropDownList.
+- `modelValue: string` — The currently selected demo value (for v-model binding).
+
+### Emits
+- `update:modelValue` — Emitted when the user selects a new demo.
+
+### Slot
+- Default slot receives an object with `{ selected }`, where `selected` is the currently selected demo value.
+- If no slot content is provided, nothing is rendered.
+
+### Example Usage
+
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { DemoSelection } from "feather-k-demo-utils";
+import BasicGrid from "./basic/BasicGrid.vue";
+import DetailsGrid from "./details/DetailsGrid.vue";
+// ...other imports
+
+const demoOptions = [
+  { text: "✔️ Basic", value: "Basic" },
+  { text: "✔️ Details", value: "Details" },
+  // ...other options
+];
+const selectedDemo = ref("Basic");
+</script>
+
+<template>
+  <DemoSelection :options="demoOptions" v-model="selectedDemo">
+    <template #default="{ selected }">
+      <BasicGrid v-if="selected === 'Basic'" />
+      <DetailsGrid v-if="selected === 'Details'" />
+      <!-- ...other demo components... -->
+    </template>
+  </DemoSelection>
+</template>
+```
+
+### Behavior
+- The DropDownList is only rendered if slot content is provided.
+- The selected value is always kept in sync with the parent via v-model.
+- The slot prop `selected` is the current value, so you can use it for conditional rendering.
+
+### Benefits
+- Consistent demo navigation UI across projects.
+- Keeps demo selection logic and rendering decoupled and reusable.
+- No need to maintain a local DemoSelection.vue; always use the package version for updates and bugfixes.
 
 # Multi-Demo Navigation with DropDownList
 

package/README.md

@@ -1,88 +1,126 @@
-# 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-<control> demo projects, including:
-
-- Shared demo styles
-- Shared demo UI components (such as `DemoStats`, `DemoDebug`, 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
-		- `DemoDebug`: Collapsible debug panel (slot-based)
-		- `DemoSettings`: Collapsible settings panel (slot-based)
-- `feather-k-demo-utils/utils`
-	- Utility helpers used by demo apps
-- `feather-k-demo-utils/styles/demo.css`
-	- Demo-only stylesheet for shared demo layout and component styling
-
-## Quick Usage
-
-Install:
-
-```bash
-npm install feather-k-demo-utils
-```
-
-Import demo styles once in your app entry:
-
-```ts
-import "feather-k-demo-utils/styles/demo.css";
-```
-
-
-Import what you need:
-
-```ts
-import { DemoStats, DemoDebug, DemoSettings } from "feather-k-demo-utils";
-import { getFeatherkStylesVersionFromUrl } from "feather-k-demo-utils/utils";
-```
-
-### DemoDebug
-
-Collapsible debug panel. Slot content is only shown if provided.
-
-```vue
-<DemoDebug>
-	<pre>{{ debugInfo }}</pre>
-</DemoDebug>
-```
-
-### DemoSettings
-
-Collapsible settings panel. Slot content is only shown if provided.
-
-```vue
-<DemoSettings>
-	<div>Settings content here</div>
-</DemoSettings>
-```
-
-
-For full integration steps (Vite env setup, stylesheet injection, and component usage), see [DEMO-UTILS.md](https://github.com/NantHealth/feather-k-demo-utils/blob/integration/DEMO-UTILS.md).
-
-## Publishing
-
-Package publishing is handled via npm.
-
-```bash
-npm login
-npm run build
-npm publish
-```
-
-## Build-Time Publish Date
-
+# 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-<control> demo projects, including:
+
+- Shared demo styles
+- Shared demo UI components (such as `DemoStats`, `DemoDebug`, 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
+		- `DemoDebug`: Collapsible debug 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/styles/demo.css`
+	- Demo-only stylesheet for shared demo layout and component styling
+
+## Quick Usage
+
+Install:
+
+```bash
+npm install feather-k-demo-utils
+```
+
+Import demo styles once in your app entry:
+
+```ts
+import "feather-k-demo-utils/styles/demo.css";
+```
+
+
+
+Import what you need:
+
+```ts
+import { DemoStats, DemoDebug, DemoSettings, DemoNotes, DemoSelection } 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:
+
+```vue
+<DemoSelection :options="demoOptions" v-model="selectedDemo">
+	<template #default="{ selected }">
+		<Demo1 v-if="selected === 'demo1'" />
+		<Demo2 v-else-if="selected === 'demo2'" />
+	</template>
+</DemoSelection>
+```
+
+Where `demoOptions` is an array like:
+
+```js
+const demoOptions = [
+	{ text: "Demo 1", value: "demo1" },
+	{ text: "Demo 2", value: "demo2" },
+];
+```
+
+### DemoDebug
+
+Collapsible debug panel. Slot content is only shown if provided.
+
+```vue
+<DemoDebug>
+	<pre>{{ debugInfo }}</pre>
+</DemoDebug>
+```
+
+### DemoSettings
+
+Collapsible settings panel. Slot content is only shown if provided.
+
+```vue
+<DemoSettings>
+	<div>Settings content here</div>
+</DemoSettings>
+```
+
+### DemoNotes
+
+Panel for displaying notes or additional information. Slot content is only shown if provided.
+
+```vue
+<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](https://github.com/NantHealth/feather-k-demo-utils/blob/integration/DEMO-UTILS.md).
+
+## Publishing
+
+Package publishing is handled via npm.
+
+```bash
+npm login
+npm run build
+npm publish
+```
+
+## 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.