feather-k-demo-utils 0.0.26 → 0.0.28

package/.github/instructions/featherk-demo-integration.md

@@ -0,0 +1,86 @@
+# Feather K Demo Integration Instructions
+
+## Goal
+Standardize how demo projects integrate feather-k-demo-utils and FeatherK styles so each demo is consistent, version-aware, and easy to publish.
+
+## Required Checks
+
+1. Verify feather-k-demo-utils dependency is current
+- Read package.json dependencies.
+- Check latest published version from npm for feather-k-demo-utils.
+- If package.json is behind, update dependency to latest compatible version and note the change.
+
+2. Verify FeatherK styles dependency and CDN strategy
+- Keep @featherk/styles in dependencies for local compatibility.
+- In Vite config, define a FeatherK CDN URL constant using a version token, typically latest unless the demo requires a pinned version.
+
+3. Verify publish metadata in Vite config
+- Ensure import.meta.env.PUBLISH_DATE is defined via Vite define.
+- If process.env is used in vite.config.ts, ensure @types/node exists in devDependencies.
+
+4. Verify HTML stylesheet injection via Vite
+- Prefer transformIndexHtml plugin in vite.config.ts to inject the stylesheet link into head.
+- Keep index.html free of hardcoded FeatherK stylesheet link when using plugin injection.
+
+5. Verify demo CSS integration
+- Ensure main entry imports feather-k-demo-utils/styles/demo.css.
+- Keep local scoped overrides minimal and component-focused.
+- Comment out any global styles that may conflict with the base demo styles and report them for resolution.
+
+6. Verify demo stats wiring
+- Ensure App imports DemoStats from feather-k-demo-utils.
+- Ensure version is derived from the FeatherK CDN URL using getFeatherkStylesVersionFromUrl.
+- Ensure publish date and version are passed to DemoStats.
+
+7. Verify Volta configuration in package.json
+- Ensure a top-level `volta` block exists in package.json.
+- Ensure pinned `node` is the latest active LTS release used by the repo standard.
+- Ensure pinned `npm` is the latest stable version compatible with that Node LTS.
+- Prefer keeping the `volta` block at the end of package.json for consistency.
+
+## Expected Integration Pattern
+
+1. package.json
+- dependencies include feather-k-demo-utils and @featherk/styles
+- devDependencies include @types/node when vite.config.ts references process.env
+- includes a top-level `volta` block with pinned runtime tooling (`node` and `npm`)
+- `volta.node` targets latest active Node LTS for the repo
+- `volta.npm` targets latest npm compatible with that Node LTS
+
+2. vite.config.ts
+- Define FEATHERK_STYLES_CDN_URL constant
+- Define PUBLISH_DATE via define import.meta.env.PUBLISH_DATE
+- Add transformIndexHtml plugin that injects:
+  - tag: link
+  - rel: stylesheet
+  - href: FEATHERK_STYLES_CDN_URL
+  - injectTo: head
+- Define import.meta.env.FEATHERK_STYLES_CDN_URL for app usage
+
+3. index.html
+- No hardcoded FeatherK stylesheet URL if transformIndexHtml is active
+
+4. main.ts
+- Import feather-k-demo-utils/styles/demo.css once at app bootstrap
+
+5. App.vue
+- Import DemoStats and getFeatherkStylesVersionFromUrl
+- Compute version from import.meta.env.FEATHERK_STYLES_CDN_URL
+- Render DemoStats with version and publish date
+
+## Validation Steps
+
+1. Build succeeds with no TypeScript errors.
+2. dist index output contains injected FeatherK stylesheet link.
+3. App displays demo stats with version and publish date.
+4. Demo CSS classes render correctly.
+5. Volta config exists and the pinned Node version matches project expectations.
+6. Volta config includes pinned `node` and `npm` versions.
+7. `volta.node` and `volta.npm` align with latest LTS + compatible npm policy.
+
+## Notes
+
+- Default FeatherK CDN version should usually be latest for demos unless testing a specific release.
+- Prefer centralizing version constants in vite.config.ts rather than duplicating values across files.
+- Keep instructions minimal, deterministic, and reusable across component demo repositories.
+- For runtime tooling, prefer latest active Node LTS and latest compatible npm unless a repo-specific exception is documented.

package/DEMO-UTILS.md

@@ -0,0 +1,133 @@
+# feather-k-demo-utils integration notes
+
+Demo projects should use `feather-k-demo-utils` for demo styling and a shared stats footer. Use the steps below to integrate a consuming Vite + Vue 3 app.
+
+## 1) Install the package
+
+```bash
+npm install feather-k-demo-utils
+```
+
+For TypeScript projects that need Node type definitions (for example when using `process`), also install the Node types:
+
+```bash
+npm install --save-dev @types/node
+```
+
+## 2) Import demo CSS once (app entry)
+
+```ts
+// src/main.ts
+import "feather-k-demo-utils/styles/demo.css";
+```
+
+This brings in demo-only styling (layout, spacing, and `DemoStats` styles).
+
+## 3) Configure required Vite env values and HTML style injection
+
+This setup injects `FEATHERK_STYLES_CDN_URL` and `PUBLISH_DATE` using Vite `define`, and also injects a `<link rel="stylesheet">` tag into `index.html` via a Vite plugin.
+
+```ts
+// vite.config.ts
+import { defineConfig, type Plugin } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+const version = "latest";
+const FEATHERK_STYLES_CDN_URL =
+  `https://cdn.jsdelivr.net/npm/@featherk/styles@${version}/dist/v8.2.0/css/featherk.css`;
+
+const injectFeatherkStyles = (): Plugin => ({
+  name: "inject-featherk-styles",
+  transformIndexHtml() {
+    return [
+      {
+        tag: "link",
+        attrs: {
+          rel: "stylesheet",
+          href: FEATHERK_STYLES_CDN_URL,
+        },
+        injectTo: "head",
+      },
+    ];
+  },
+});
+
+export default defineConfig({
+  plugins: [vue(), injectFeatherkStyles()],
+  define: {
+    "import.meta.env.FEATHERK_STYLES_CDN_URL": JSON.stringify(
+      FEATHERK_STYLES_CDN_URL,
+    ),
+    "import.meta.env.PUBLISH_DATE": JSON.stringify(
+      process.env.PUBLISH_DATE ||
+        new Date().toLocaleString("en-US", {
+          year: "numeric",
+          month: "2-digit",
+          day: "2-digit",
+          hour: "2-digit",
+          minute: "2-digit",
+          hour12: true,
+          dayPeriod: "short",
+        }),
+    ),
+  },
+});
+```
+
+Notes:
+- The `inject-featherk-styles` plugin writes the stylesheet link into the final `index.html` `<head>`.
+- `FEATHERK_STYLES_CDN_URL` should point at the exact `@featherk/styles` CSS you want to showcase.
+- `PUBLISH_DATE` can be injected at build time (for CI) or defaulted as shown.
+
+## 4) Render DemoStats in your app
+
+```html
+<script setup lang="ts">
+import { computed } from "vue";
+import { DemoStats } from "feather-k-demo-utils";
+import { getFeatherkStylesVersionFromUrl } from "feather-k-demo-utils/utils";
+
+const PUBLISH_DATE = import.meta.env.PUBLISH_DATE;
+const version = computed(() => getFeatherkStylesVersionFromUrl(import.meta.env.FEATHERK_STYLES_CDN_URL),
+);
+</script>
+
+<template>
+  <DemoStats v-if="version" :version="version" :publishDate="PUBLISH_DATE" />
+</template>
+```
+
+`DemoStats` renders the version and publish date, and links to the demo-utils README if the publish date is missing.
+
+## 5) (Optional) Pin the dependency version
+
+```json
+{
+  "dependencies": {
+    "feather-k-demo-utils": "^0.0.26"
+  }
+}
+```
+
+### Demo Layout Structure (required for consistent utility styles)
+
+```html
+<!-- App.vue top level "demo-app" -->
+<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>
+</div>
+
+Keep this aligned with whichever demo-utils release you want to display.

package/README.md

@@ -1,33 +1,61 @@
-# Vue 3 + TypeScript + Vite
+# feather-k-demo-utils
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+Shared demo utilities for Feather K Vue component demo repositories.
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+## Purpose
 
-## Publishing
+`feather-k-demo-utils` centralizes common demo functionality used across feather-k-<control> demo projects, including:
 
-Here’s how to authenticate and publish your package to npm using your npm username
+- Shared demo styles
+- Shared demo UI components (such as `DemoStats`)
+- Shared utility helpers (for example, CDN/version helpers)
 
-Open a terminal in your project root.
+This package is intended for internal/demo scenarios and consistency across Feather K demos, not as a general-purpose application UI library.
 
-Run:
-npm login
+## What's Included
 
-Enter your username: (input is hidden)
-Enter your password (input is hidden)
-Enter your email address
->If you have 2FA enabled, enter your OTP code when prompted.
->After successful login, run:
->npm publish
->If your package is scoped (e.g., @featherk/feather-k-demo-utils), use:
->increment version number...
-npm publish --access public
+- `feather-k-demo-utils` (root exports)
+	- Demo components and top-level exports
+- `feather-k-demo-utils/components`
+	- Component-focused exports
+- `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
 
-## Setting the Publish Date in Consuming Projects
+## Quick Usage
 
-This package no longer exposes an in-package `PUBLISH_DATE`. If you need a build-time publish date in your consuming app, set it via your build (for example, with Vite's `define` option) and consume it from your application code directly.
+Install:
 
-## Quick Usage
+```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 } from "feather-k-demo-utils";
+import { getFeatherkStylesVersionFromUrl } from "feather-k-demo-utils/utils";
+```
+
+For full integration steps (Vite env setup, stylesheet injection, and `DemoStats` 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
 
-<!-- link to DEMO-UTIL.md -->
-see [DEMO-UTILS.md](https://github.com/NantHealth/feather-k-demo-utils/blob/integration/DEMO-UTILS.md)
+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.

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "feather-k-demo-utils",
   "private": false,
-  "version": "0.0.26",
+  "version": "0.0.28",
   "type": "module",
   "main": "lib/index.es.js",
   "module": "lib/index.es.js",
   "types": "lib/index.d.ts",
   "author": "Feather K Team",
   "license": "MIT",
-  "description": "Utilties for feather-k demos only",
+  "description": "Utilities for feather-k demos only",
   "repository": {
     "type": "git",
     "url": "https://github.com/NantHealth/feather-k-demo-utils.git"
@@ -60,6 +60,8 @@
     "vue-tsc": "^3.1.4"
   },
   "files": [
+    "DEMO-UTILS.md",
+    ".github/instructions/featherk-demo-integration.md",
     "lib/index.es.js",
     "lib/index.d.ts",
     "lib/index.umd.js",
@@ -67,5 +69,9 @@
     "lib/utils",
     "lib/styles",
     "lib/*.js"
-  ]
+  ],
+  "volta": {
+    "node": "24.14.0",
+    "npm": "11.11.0"
+  }
 }