picocrank 1.23.0 → 1.24.0

package/AGENTS.md

@@ -0,0 +1,11 @@
+# PicoCrank — agent notes
+
+PicoCrank is a Vue component library demo built on the [Femtocrank](https://github.com/jamesread/femtocrank) global CSS theme. Reusable components live under `vue/components/`; example pages under `vue/examples/`.
+
+## UI patterns
+
+- [Buttons with icons](docs/buttons-with-icons.md) — Femtocrank `.inline-icon`, Hugeicons, karma variants (icon + text and icon-only).
+
+## Examples app
+
+Run the Vite dev server and browse example routes (e.g. `/buttons-example`) for live reference implementations.

package/docs/buttons-with-icons.md

@@ -0,0 +1,97 @@
+# Buttons with icons (PicoCrank / Femtocrank)
+
+Brief reference for reproducing icon buttons as shown in `vue/examples/ButtonsExample.vue`.
+
+## Prerequisites
+
+- **Femtocrank** `^2.5.3` or newer (provides `.inline-icon` and button/karma styles).
+- **Hugeicons**: `@hugeicons/vue` and `@hugeicons/core-free-icons`.
+- There is **no** `Button` Vue component — use plain HTML `<button>` (or `<a class="button">` for links).
+
+## Pattern
+
+1. Put **`inline-icon`** on the `<button>` (Femtocrank flex layout: icon + label, aligned with gap).
+2. Add optional **karma intent** classes on the same element: `neutral`, `good`, `bad`, `warning`.
+3. Render **`HugeiconsIcon`** at `1em` × `1em` with **`strokeWidth` `2.5`** for button-sized icons.
+4. Set **`aria-hidden="true"`** on the icon when visible text is present.
+5. For **icon-only** buttons, omit the label and set **`aria-label`** on the button instead.
+
+## Icon and text
+
+```vue
+<script setup>
+import { HugeiconsIcon } from '@hugeicons/vue'
+import { Add01Icon } from '@hugeicons/core-free-icons'
+
+const iconStrokeWidth = 2.5
+</script>
+
+<template>
+  <button type="button" class="inline-icon good">
+    <HugeiconsIcon
+      :icon="Add01Icon"
+      width="1em"
+      height="1em"
+      :strokeWidth="iconStrokeWidth"
+      aria-hidden="true"
+    />
+    <span>Add item</span>
+  </button>
+</template>
+```
+
+## Icon only
+
+```vue
+<button type="button" class="inline-icon neutral" aria-label="Edit">
+  <HugeiconsIcon
+    :icon="EditIcon"
+    width="1em"
+    height="1em"
+    :strokeWidth="iconStrokeWidth"
+    aria-hidden="true"
+  />
+</button>
+```
+
+## Karma variants
+
+Apply on the same `<button>` as `inline-icon`:
+
+| Class     | Use for              |
+|-----------|----------------------|
+| (none)    | Default              |
+| `neutral` | Secondary / toolbar  |
+| `good`    | Primary / confirm    |
+| `bad`     | Destructive          |
+| `warning` | Caution              |
+
+Example: `<button type="button" class="inline-icon bad" aria-label="Delete">…</button>`
+
+## Toolbars
+
+Group buttons in a flex row (example-only layout, not from Femtocrank):
+
+```vue
+<div role="toolbar" class="buttons-row">
+  <!-- buttons here -->
+</div>
+```
+
+```css
+.buttons-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+```
+
+## Do not
+
+- Do not create a wrapper `Button` component unless the project already has one.
+- Do not omit `aria-label` on icon-only buttons.
+- Do not set `aria-hidden` on the button itself — only on the icon when a visible label exists.
+
+## Live example
+
+Route: `/buttons-example` — sections **Icon and text** and **Icon only** in `vue/examples/ButtonsExample.vue`.

package/index.html

@@ -24,7 +24,7 @@
 	
 	<script type = "module">
 		import { createApp } from 'vue';
-		import App from './vue/views/App.vue';
+		import App from './vue/examples/App.vue';
 		import router from './router.js';
 
 		const app = createApp(App)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picocrank",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "A set of zero dependency Vue components built on the Femtocrank global CSS theme.",
   "main": "vite.config.js",
   "scripts": {
@@ -21,7 +21,7 @@
     "@hugeicons/core-free-icons": "^4.2.3",
     "@hugeicons/vue": "^1.0.7",
     "@vitejs/plugin-vue": "^6.0.8",
-    "femtocrank": "^2.5.2",
+    "femtocrank": "^2.5.3",
     "unplugin-vue-components": "^32.1.0",
     "vite": "^8.2.1",
     "vue": "^3.5.41",

package/router.js

@@ -20,7 +20,7 @@ const routes = [
   {
     name: 'Welcome',
     path: '/',
-    component: () => import('./vue/views/Welcome.vue'),
+    component: () => import('./vue/examples/Welcome.vue'),
     meta: {
       title: 'Welcome',
       icon: HomeIcon,
@@ -29,7 +29,7 @@ const routes = [
   {
     name: 'PageStructure',
     path: '/page-structure',
-    component: () => import('./vue/views/PageStructure.vue'),
+    component: () => import('./vue/examples/PageStructure.vue'),
     meta: {
       title: 'Page structure',
       icon: LayoutGridIcon,
@@ -38,7 +38,7 @@ const routes = [
   {
     name: 'ThemePreview',
     path: '/theme-preview',
-    component: () => import('./vue/views/ThemePreview.vue'),
+    component: () => import('./vue/examples/ThemePreview.vue'),
     meta: {
       title: 'Theme Switcher',
       icon: PaintBoardIcon,
@@ -47,7 +47,7 @@ const routes = [
   {
     name: 'UserDetails',
     path: '/user',
-    component: () => import('./vue/views/UserDetails.vue'),
+    component: () => import('./vue/examples/UserDetails.vue'),
     meta: {
       title: 'User details',
       icon: UserIcon,
@@ -57,7 +57,7 @@ const routes = [
     name: 'TableExample',
     path: '/table-example',
     title: 'Table Example',
-    component: () => import('./vue/views/TableExample.vue'),
+    component: () => import('./vue/examples/TableExample.vue'),
     meta: {
       title: 'Table',
       icon: TableIcon,
@@ -66,7 +66,7 @@ const routes = [
   {
     name: 'TableRemoteExample',
     path: '/table-remote-example',
-    component: () => import('./vue/views/TableRemoteExample.vue'),
+    component: () => import('./vue/examples/TableRemoteExample.vue'),
     meta: {
       title: 'Remote table',
       icon: TableIcon,
@@ -75,7 +75,7 @@ const routes = [
   {
     name: 'ViewItem',
     path: '/view-item/:id',
-    component: () => import('./vue/views/ViewItem.vue'),
+    component: () => import('./vue/examples/ViewItem.vue'),
     props: true,
     meta: {
       title: 'View item',
@@ -85,7 +85,7 @@ const routes = [
   {
     name: 'Admin',
     path: '/admin',
-    component: () => import('./vue/views/Admin.vue'),
+    component: () => import('./vue/examples/Admin.vue'),
     meta: {
       title: 'Admin',
       icon: SecurityValidationIcon,
@@ -94,7 +94,7 @@ const routes = [
   {
     name: 'CalendarExample',
     path: '/calendar-example',
-    component: () => import('./vue/views/CalendarExample.vue'),
+    component: () => import('./vue/examples/CalendarExample.vue'),
     props: true,
     meta: {
       title: 'Calendar',
@@ -104,7 +104,7 @@ const routes = [
   {
     name: 'Login',
     path: '/login',
-    component: () => import('./vue/views/Login.vue'),
+    component: () => import('./vue/examples/Login.vue'),
     meta: {
       title: 'Login',
       icon: SecurityValidationIcon,
@@ -113,7 +113,7 @@ const routes = [
   {
     name: 'ButtonsExample',
     path: '/buttons-example',
-    component: () => import('./vue/views/ButtonsExample.vue'),
+    component: () => import('./vue/examples/ButtonsExample.vue'),
     meta: {
       title: 'Buttons',
       icon: CursorPointer01Icon,
@@ -122,7 +122,7 @@ const routes = [
   {
     name: 'FormExample',
     path: '/form-example',
-    component: () => import('./vue/views/FormExample.vue'),
+    component: () => import('./vue/examples/FormExample.vue'),
     meta: {
       title: 'Forms',
       icon: EditIcon,
@@ -131,7 +131,7 @@ const routes = [
   {
     name: 'ReadOnlyTextAreaExample',
     path: '/readonly-textarea-example',
-    component: () => import('./vue/views/ReadOnlyTextAreaExample.vue'),
+    component: () => import('./vue/examples/ReadOnlyTextAreaExample.vue'),
     meta: {
       title: 'Read-only output',
       icon: ClipboardCopyIcon,
@@ -140,7 +140,7 @@ const routes = [
   {
     name: 'StatusExample',
     path: '/status-example',
-    component: () => import('./vue/views/StatusExample.vue'),
+    component: () => import('./vue/examples/StatusExample.vue'),
     meta: {
       title: 'Status & notifications',
       icon: StatusIcon,
@@ -149,7 +149,7 @@ const routes = [
   {
     name: 'DialogExample',
     path: '/dialog-example',
-    component: () => import('./vue/views/DialogExample.vue'),
+    component: () => import('./vue/examples/DialogExample.vue'),
     meta: {
       title: 'Dialog',
       icon: InformationCircleIcon,
@@ -158,7 +158,7 @@ const routes = [
   {
     name: 'TabsExample',
     path: '/tabs-example',
-    component: () => import('./vue/views/TabsExample.vue'),
+    component: () => import('./vue/examples/TabsExample.vue'),
     meta: {
       title: 'Tabs',
       icon: Menu01Icon,
@@ -167,7 +167,7 @@ const routes = [
   {
     name: 'NavigationGridExample',
     path: '/navigation-grid',
-    component: () => import('./vue/views/NavigationGridExample.vue'),
+    component: () => import('./vue/examples/NavigationGridExample.vue'),
     meta: {
       title: 'Navigation Grid',
       icon: Navigation01Icon,
@@ -176,7 +176,7 @@ const routes = [
   {
     name: 'LoginExample',
     path: '/login-example',
-    component: () => import('./vue/views/LoginExample.vue'),
+    component: () => import('./vue/examples/LoginExample.vue'),
     meta: {
       title: 'Login',
       icon: SecurityValidationIcon,

package/vite.config.js

@@ -94,7 +94,7 @@ export default defineConfig({
   plugins: [
     themesIndexPlugin(),
     Components({
-      dirs: "./vue/",
+      dirs: ['./vue/components/'],
       extensions: ['vue'],
       deep: true,
       dts: false,

package/vue/components/FormField.vue

@@ -1,7 +1,35 @@
 <template>
 	<label v-if="!fake" :for="controlId" :class="{ disabled }">{{ label }}</label>
 	<span v-else class="fake-label" :class="{ disabled }">{{ label }}</span>
-	<slot />
+	<div v-if="hasFieldMeta" class="form-field-control">
+		<template v-if="descriptionAbove">
+			<div v-if="description || docsUrl" class="form-field-meta">
+				<p v-if="description" class="subtle form-field-description">{{ description }}</p>
+				<a
+					v-if="docsUrl"
+					class="form-field-docs-link"
+					:href="docsUrl"
+					target="_blank"
+					rel="noopener noreferrer"
+				>{{ docsLinkTitle }}</a>
+			</div>
+			<slot />
+		</template>
+		<template v-else>
+			<slot />
+			<div v-if="description || docsUrl" class="form-field-meta">
+				<p v-if="description" class="subtle form-field-description">{{ description }}</p>
+				<a
+					v-if="docsUrl"
+					class="form-field-docs-link"
+					:href="docsUrl"
+					target="_blank"
+					rel="noopener noreferrer"
+				>{{ docsLinkTitle }}</a>
+			</div>
+		</template>
+	</div>
+	<slot v-else />
 </template>
 
 <script setup>
@@ -12,6 +40,22 @@ const props = defineProps({
 		type: String,
 		required: true,
 	},
+	description: {
+		type: String,
+		default: '',
+	},
+	descriptionAbove: {
+		type: Boolean,
+		default: false,
+	},
+	docsUrl: {
+		type: String,
+		default: '',
+	},
+	docsUrlTitle: {
+		type: String,
+		default: '',
+	},
 	for: {
 		type: String,
 		default: '',
@@ -31,6 +75,8 @@ const props = defineProps({
 })
 
 const controlId = computed(() => props.htmlFor || props.for)
+const hasFieldMeta = computed(() => Boolean(props.description || props.docsUrl))
+const docsLinkTitle = computed(() => props.docsUrlTitle || props.docsUrl)
 </script>
 
 <style scoped>
@@ -39,4 +85,26 @@ label.disabled,
 	color: var(--disabled-text-color);
 	cursor: not-allowed;
 }
+
+.form-field-control {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+	width: 100%;
+}
+
+.form-field-meta {
+	display: flex;
+	flex-direction: column;
+	gap: 0.35rem;
+}
+
+.form-field-description {
+	margin: 0;
+}
+
+.form-field-docs-link {
+	font-size: 0.9em;
+	align-self: flex-start;
+}
 </style>

package/vue/{views → examples}/ButtonsExample.vue

@@ -5,7 +5,9 @@
 	>
 		<p>
 			Buttons use the global Femtocrank theme. Apply karma classes for intent, or
-			rely on <code>type</code> attributes for form semantics.
+			rely on <code>type</code> attributes for form semantics. Use
+			<code>.inline-icon</code> on buttons with icons, and
+			<code>aria-label</code> when there is no visible text.
 		</p>
 	</Section>
 
@@ -19,6 +21,47 @@
 		</div>
 	</Section>
 
+	<Section title="Icon and text" subtitle="Hugeicons with a visible label">
+		<div role="toolbar" class="buttons-row">
+			<button type="button" class="inline-icon">
+				<HugeiconsIcon :icon="Add01Icon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+				<span>Add item</span>
+			</button>
+			<button type="button" class="inline-icon neutral">
+				<HugeiconsIcon :icon="EditIcon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+				<span>Edit</span>
+			</button>
+			<button type="button" class="inline-icon good">
+				<HugeiconsIcon :icon="SearchIcon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+				<span>Search</span>
+			</button>
+			<button type="button" class="inline-icon">
+				<HugeiconsIcon :icon="Copy01Icon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+				<span>Copy</span>
+			</button>
+		</div>
+	</Section>
+
+	<Section title="Icon only" subtitle="Hugeicons without visible text">
+		<div role="toolbar" class="buttons-row">
+			<button type="button" class="inline-icon" aria-label="Add item">
+				<HugeiconsIcon :icon="Add01Icon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+			</button>
+			<button type="button" class="inline-icon neutral" aria-label="Edit">
+				<HugeiconsIcon :icon="EditIcon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+			</button>
+			<button type="button" class="inline-icon good" aria-label="Search">
+				<HugeiconsIcon :icon="SearchIcon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+			</button>
+			<button type="button" class="inline-icon bad" aria-label="Delete">
+				<HugeiconsIcon :icon="Delete02Icon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+			</button>
+			<button type="button" class="inline-icon neutral" aria-label="Settings">
+				<HugeiconsIcon :icon="Settings01Icon" width="1em" height="1em" :strokeWidth="iconStrokeWidth" aria-hidden="true" />
+			</button>
+		</div>
+	</Section>
+
 	<Section title="Form actions" subtitle="Semantic button types in a fieldset">
 		<FormLayout class="buttons-demo-form" @submit.prevent="onSubmit">
 			<template #actions>
@@ -67,10 +110,20 @@
 
 <script setup>
 import { ref } from 'vue'
+import { HugeiconsIcon } from '@hugeicons/vue'
+import {
+	Add01Icon,
+	Copy01Icon,
+	Delete02Icon,
+	EditIcon,
+	SearchIcon,
+	Settings01Icon,
+} from '@hugeicons/core-free-icons'
 import Section from '../components/Section.vue'
 import FormLayout from '../components/FormLayout.vue'
 
 const lastAction = ref('')
+const iconStrokeWidth = 2.5
 
 function onSubmit() {
 	lastAction.value = 'Form submitted.'

package/vue/{views → examples}/FormExample.vue

@@ -8,7 +8,11 @@
 		</template>
 
 		<FormLayout @submit.prevent="handleSubmit">
-			<FormField label="Name" for="name">
+			<FormField
+				label="Name"
+				for="name"
+				description="Your full name as it will appear on your profile."
+			>
 				<input 
 					id="name"
 					v-model="formData.name" 
@@ -46,7 +50,14 @@
 				</select>
 			</FormField>
 
-			<FormField label="Compensation" fake>
+			<FormField
+				label="Compensation"
+				fake
+				description-above
+				description="Select the incentive plan that applies to this role."
+				docs-url="https://github.com/jamesread/femtocrank"
+				docs-url-title="Femtocrank documentation"
+			>
 				<RadioGroup
 					v-model="formData.compensation"
 					name="compensation"
@@ -55,7 +66,14 @@
 				/>
 			</FormField>
 
-			<FormField label="Accessibility requirements" fake>
+			<FormField
+				label="Accessibility requirements"
+				fake
+				description-above
+				description="Choose any accommodations needed for this role."
+				docs-url="https://www.w3.org/WAI/fundamentals/accessibility-intro/"
+				docs-url-title="Web accessibility introduction"
+			>
 				<CheckGroup
 					v-model="formData.accessibility"
 					name="accessibility"
@@ -63,7 +81,13 @@
 				/>
 			</FormField>
 
-			<FormField label="Email" for="email">
+			<FormField
+				label="Email"
+				for="email"
+				description="We'll use this address for account notifications only."
+				docs-url="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email"
+				docs-url-title="HTML email input reference"
+			>
 				<input 
 					id="email"
 					v-model="formData.email" 
@@ -81,7 +105,13 @@
 				/>
 			</FormField>
 
-			<FormField label="Website" for="website">
+			<FormField
+				label="Website"
+				for="website"
+				description="Include https:// for external links."
+				docs-url="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/url"
+				docs-url-title="HTML URL input reference"
+			>
 				<input 
 					id="website"
 					v-model="formData.website" 
@@ -141,7 +171,11 @@
 				</div>
 			</FormField>
 
-			<FormField label="Comments" for="comments">
+			<FormField
+				label="Comments"
+				for="comments"
+				description="Optional feedback or notes about this submission."
+			>
 				<textarea
 					id="comments"
 					v-model="formData.comments"