@kiva/kv-components 8.11.3 → 8.12.0

package/dist/vue/KvVotingCardV2.js

@@ -1,65 +1,65 @@
 import x from "./KvVotingCardV22.js";
-import { resolveComponent as s, openBlock as l, createElementBlock as r, normalizeStyle as b, createElementVNode as o, toDisplayString as i, createTextVNode as w, createCommentVNode as c, createVNode as d, createBlock as u, withCtx as a } from "vue";
+import { resolveComponent as l, openBlock as s, createElementBlock as c, normalizeStyle as b, createElementVNode as o, toDisplayString as n, createTextVNode as w, createCommentVNode as r, createVNode as d, createBlock as h, withCtx as a } from "vue";
 import "./KvVotingCardV2.css";
 import g from "../_virtual/_plugin-vue_export-helper.js";
-const h = { class: "tw-flex-grow-0 tw-text-white" }, k = { class: "tw-italic tw-pb-1" }, p = { class: "tw-pb-1.5" }, y = { class: "tw-block md:tw-flex tw-justify-between" }, V = {
+const u = { class: "tw-flex-grow-0 tw-text-white" }, k = { class: "tw-italic tw-pb-1" }, p = { class: "tw-pb-1.5" }, y = { class: "tw-block md:tw-flex tw-justify-between" }, V = {
   key: 0,
   class: "tw-flex tw-items-center tw-w-full tw-max-w-16"
-}, C = { class: "tw-ml-2" }, L = { class: "tw-pb-1.5" };
-function B(N, n, t, e, K, O) {
-  const _ = s("kv-progress-bar"), m = s("kv-button"), f = s("KvLightbox");
-  return l(), r("div", {
+}, C = { class: "tw-ml-2" }, L = { class: "tw-text-title" }, B = { class: "tw-pb-1.5" };
+function N(K, i, t, e, O, P) {
+  const _ = l("kv-progress-bar"), m = l("kv-button"), f = l("KvLightbox");
+  return s(), c("div", {
     class: "vote_card tw-flex tw-flex-col tw-justify-end",
     style: b(e.cssProps)
   }, [
-    o("div", h, [
-      o("h2", k, i(t.title), 1),
+    o("div", u, [
+      o("h2", k, n(t.title), 1),
       o("p", p, [
-        w(i(e.truncatedDescription) + " ", 1),
-        e.isTruncated ? (l(), r("a", {
+        w(n(e.truncatedDescription) + " ", 1),
+        e.isTruncated ? (s(), c("a", {
           key: 0,
           class: "tw-underline tw-pl-1 tw-text-white tw-cursor-pointer",
-          onClick: n[0] || (n[0] = (v) => e.isLightboxOpen = !0)
-        }, "read more")) : c("", !0)
+          onClick: i[0] || (i[0] = (v) => e.isLightboxOpen = !0)
+        }, "read more")) : r("", !0)
       ]),
       o("div", y, [
-        t.showPercentage ? (l(), r("div", V, [
+        t.showPercentage ? (s(), c("div", V, [
           d(_, {
             class: "tw-flex-grow",
             label: "Percent of votes for " + t.description,
             value: t.percentage
           }, null, 8, ["label", "value"]),
-          o("div", C, i(t.percentage) + "% ", 1)
-        ])) : c("", !0),
-        t.showVoteButton ? (l(), u(m, {
+          o("div", C, n(t.percentage) + "% ", 1)
+        ])) : r("", !0),
+        t.showVoteButton ? (s(), h(m, {
           key: 1,
           variant: "secondary",
           class: "tw-flex-grow-0 tw-min-w-16 tw-mt-2",
           onClick: e.castVote
         }, {
-          default: a(() => n[2] || (n[2] = [
+          default: a(() => i[2] || (i[2] = [
             w(" Vote ")
           ])),
           _: 1
-        }, 8, ["onClick"])) : c("", !0)
+        }, 8, ["onClick"])) : r("", !0)
       ])
     ]),
     d(f, {
       title: t.title,
       visible: e.isLightboxOpen,
-      onLightboxClosed: n[1] || (n[1] = (v) => e.isLightboxOpen = !1)
+      onLightboxClosed: i[1] || (i[1] = (v) => e.isLightboxOpen = !1)
     }, {
       header: a(() => [
-        o("h3", null, i(t.title), 1)
+        o("h3", L, n(t.title), 1)
       ]),
       default: a(() => [
-        o("p", L, i(t.description), 1)
+        o("p", B, n(t.description), 1)
       ]),
       _: 1
     }, 8, ["title", "visible"])
   ], 4);
 }
-const S = /* @__PURE__ */ g(x, [["render", B]]);
+const T = /* @__PURE__ */ g(x, [["render", N]]);
 export {
-  S as default
+  T as default
 };

package/dist/vue/KvWideLoanCard.css

@@ -1 +1 @@
-.loan-card-use[data-v-6fba53db]:hover,.loan-card-use[data-v-6fba53db]:focus{--tw-text-opacity: 1;color:rgba(var(--text-primary),var(--tw-text-opacity, 1))}.loan-card-active-hover:hover .loan-card-use[data-v-6fba53db]{text-decoration-line:underline}.loan-card-progress[data-v-6fba53db],.loan-card-progress[data-v-6fba53db]:hover,.loan-card-progress[data-v-6fba53db]:focus{text-decoration-line:none}.loan-callouts[data-v-6fba53db] div{height:auto;flex-wrap:wrap}
+.loan-card-use[data-v-addb15e1]:hover,.loan-card-use[data-v-addb15e1]:focus{--tw-text-opacity: 1;color:rgba(var(--text-primary),var(--tw-text-opacity, 1))}.loan-card-active-hover:hover .loan-card-use[data-v-addb15e1]{text-decoration-line:underline}.loan-card-progress[data-v-addb15e1],.loan-card-progress[data-v-addb15e1]:hover,.loan-card-progress[data-v-addb15e1]:focus{text-decoration-line:none}.loan-callouts[data-v-addb15e1] div{height:auto;flex-wrap:wrap}

package/dist/vue/KvWideLoanCard.js

@@ -9,7 +9,7 @@ const B = { class: "loan-card-active-hover tw-flex-1 tw-min-w-[275px] md:tw-min-
 }, E = { key: 0 }, T = {
   class: "tw-absolute tw-bottom-1 tw-left-1 tw-text-primary tw-bg-white tw-rounded tw-p-1 tw-mb-0 tw-mr-2 tw-text-label tw-flex tw-items-center tw-h-3",
   style: { padding: "2px 6px", "text-transform": "capitalize" }
-}, S = { style: { "margin-top": "0.125rem" } }, F = { class: "tw-flex tw-flex-col tw-flex-1 tw-px-1" }, I = { class: "tw-hidden md:tw-inline-block" }, W = { class: "tw-pt-1" }, z = {
+}, S = { style: { "margin-top": "0.125rem" } }, F = { class: "tw-flex tw-flex-col tw-flex-1 tw-px-1" }, I = { class: "tw-hidden md:tw-inline-block tw-text-title" }, W = { class: "tw-pt-1" }, z = {
   key: 0,
   class: "tw-w-full",
   style: { height: "5.5rem" }
@@ -185,7 +185,7 @@ function O(h, a, t, e, j, g) {
     ])
   ], 2);
 }
-const X = /* @__PURE__ */ R(P, [["render", O], ["__scopeId", "data-v-6fba53db"]]);
+const X = /* @__PURE__ */ R(P, [["render", O], ["__scopeId", "data-v-addb15e1"]]);
 export {
   p as KV_WIDE_LOAN_CARD_FRAGMENT,
   $ as KV_WIDE_LOAN_CARD_USER_FRAGMENT,

package/dist/vue/index.d.ts

@@ -55,6 +55,8 @@ export { default as KvLoadingPlaceholder } from './KvLoadingPlaceholder.vue';
 export { default as KvLoadingSpinner } from './KvLoadingSpinner.vue';
 export { default as KvMap } from './KvMap.vue';
 export { default as KvMaterialIcon } from './KvMaterialIcon.vue';
+export { default as KvSimpleMap } from './KvSimpleMap.vue';
+export type { SimpleMapCountry } from './KvSimpleMap.vue';
 export { default as KvPageContainer } from './KvPageContainer.vue';
 export { default as KvPagination } from './KvPagination.vue';
 export { default as KvPieChart } from './KvPieChart.vue';

package/docs/make-to-vue.md

@@ -90,6 +90,31 @@ Figma Make output is presentational/demo code. Determine what needs to change:
 - **Presentational strings** -> Configurable via props/slots
 - **React animation libraries** -> CSS transitions or Vue composables (prefer no extra deps)
 
+### 1.4 New Sibling Component vs. Extending an Existing One
+
+When the source overlaps an existing kv-component, decide which path to take:
+
+| Situation | Decision |
+|-----------|----------|
+| Same renderer, additional variant or mode | Extend the existing component (new prop, new slot) |
+| Same renderer, breaking change | Create a `V2` (e.g. `KvPieChartV2`) |
+| **Different renderer or fundamentally different runtime cost** | **New sibling component** |
+
+Example: `KvMap` uses MapLibre/Leaflet (WebGL/canvas, tile fetching, ~200KB+ over the wire). A storytelling map driven by inline SVG paths and CSS transforms has none of those costs. Adding a `mode` prop would force every `KvMap` consumer to think about both paths and would bundle code most callers don't use. The right call is a sibling (`KvSimpleMap`) that shares the design vocabulary but not the implementation.
+
+**Stop-and-ask** if the choice isn't obvious — the wrong call is expensive to undo.
+
+### 1.5 External Data Modules
+
+If the source imports a generated or large data module (SVG path dictionaries, GeoJSON, country lists, icon registries, etc.), **copy it into `src/data/` as-is**. Do not translate, reformat, or hand-edit. These files are usually exported from a tool (Figma, Mapshaper, etc.) and should be treated as opaque assets.
+
+- Place the file alongside existing data assets in `src/data/`
+- Rename to a descriptive, kv-style name (e.g. `simpleMapPaths.ts`, not `svg-iw48hjyvei.ts`)
+- Re-export the default export with a typed name where useful
+- Do **not** inline the data into the component file — keeps the component readable and lets the data module be tree-shaken or lazy-imported if needed
+
+Reference: `KvMap.vue` lazy-imports `data/ne_110m_admin_0_countries.json` via dynamic `import()` to keep it out of the main chunk. Do the same when the data is large and only needed when the component actually mounts.
+
 ## Phase 2: Translation Patterns
 
 ### 2.1 React Hooks to Vue Composition API
@@ -119,36 +144,60 @@ Figma Make output is presentational/demo code. Determine what needs to change:
 
 Figma Make outputs raw Tailwind classes. Convert to kv-components patterns:
 
-- **Add `tw-` prefix** to all Tailwind utility classes
-- **Replace hardcoded font families** with design system fonts (`tw-font-sans`, `tw-font-serif`)
-- **Replace hardcoded colors** with token references where possible
-- **Replace pixel values** in Tailwind classes with spacing scale values (8px increments)
-- **Use design tokens** from `@kiva/kv-tokens` for colors, spacing, typography
+- **Always use the project's Tailwind config** (`@kiva/kv-tokens/configs/tailwind.config.js`) as the source of truth for available utilities, the `tw-` prefix, the spacing scale (8px-based, not Tailwind's default 4px), and the colour palette. Don't introduce raw hex values, hardcoded `px`/`rem` literals, or arbitrary class names where a token-backed utility exists.
+- **Apply the `tw-` prefix everywhere.** That includes class attributes in markup *and* `@apply` directives inside `<style lang="postcss" scoped>` blocks. `@apply tw-w-4 tw-h-4 tw-bg-white tw-border tw-border-tertiary tw-rounded-xs;` is the preferred way to assemble shared styles and pseudo-state rules; raw CSS belongs only where no utility exists (e.g. one-off `box-shadow` values, animation keyframes).
+- **Replace hardcoded font families** with design system fonts (`tw-font-sans`, `tw-font-serif`).
+- **Replace hardcoded colors** with token references — semantic Tailwind utilities (`tw-bg-primary`, `tw-text-secondary`, `tw-border-tertiary`) first, then named-palette utilities (`tw-bg-eco-green-2`, `tw-text-gray-300`); reach into `kvTokensPrimitives.colors[...]` from JS only when the colour must reach a non-class consumer (e.g. an SVG `:fill` binding).
+- **Replace pixel values** in Tailwind classes with spacing scale values (8px increments). `tw-w-4` = 32px, not 16px — verify against the token scale, not Tailwind defaults.
+- **Reference the kv-tokens skills** as the canonical guide for any text-styling decision before writing custom CSS. Start with [@kiva/kv-tokens/docs/skills/typography.md](../../kv-tokens/docs/skills/typography.md) for the semantic type scale, heading hierarchy, font pairing, and HTML / Tailwind mappings — always consult it before picking a heading element or text utility.
 
 ### 2.4 Animation Translation
 
-Prefer CSS transitions over JavaScript animation libraries:
+Prefer CSS-native animations: CSS transitions, Tailwind utility classes, and Vue's built-in `<Transition>` / `<TransitionGroup>` for enter/leave. Reach for a JS-driven composable only when the animation is genuinely numeric (count-up, interpolated values, multi-step choreography that can't be expressed declaratively).
 
 | Figma Make / React | Vue Equivalent |
 |--------------------|----------------|
-| `motion/react` animate prop | CSS `transition` property |
-| `transition={{ duration: 0.5 }}` | `transition: property 500ms ease-in-out` |
+| `motion.div` with `animate={...}` | Bind reactive style/class; let CSS transition handle the tween |
+| `transition={{ duration: 0.5 }}` | `transition: property 500ms ease-in-out` (or `tw-transition tw-duration-500`) |
+| `transition={{ ease: [...] }}` | `transition-timing-function: cubic-bezier(...)` |
 | Staggered animations | Computed `transition-delay` per item index |
-| Spring animations | CSS `cubic-bezier()` or `ease-in-out` |
+| Spring animations | CSS `cubic-bezier()` or `ease-in-out` (springs rarely visibly differ at small distances) |
+| `<AnimatePresence>` + `initial`/`animate`/`exit` | Vue `<Transition>` with `enter-from`/`enter-to`/`leave-from`/`leave-to` classes |
 | `requestAnimationFrame` hooks | Vue composable with `onMounted`/`onUnmounted` lifecycle |
 | Opacity/transform tweens | CSS transitions on those properties |
+| `setTimeout`-driven cycles | Vue composable that owns the timer set + cleanup (see 2.5) |
 
-For complex numeric animations (count-up, interpolation), create a composable in `src/utils/`:
+Guidelines:
 
-```ts
-// src/utils/useCountUp.ts
-import { ref, watch, onUnmounted } from 'vue';
+- **Default to declarative.** If the animation can be expressed as "this style depends on this state, transition between them," it belongs in CSS — not in a JS animation loop.
+- **One key per remountable element.** When porting `AnimatePresence` keyed children, preserve the `:key` on the Vue side so `<Transition>` treats each instance as a fresh mount/unmount.
+- **Match perceived timing, not the exact curve.** Spring → ease-in-out and motion's default cubic → a similar `cubic-bezier` are acceptable substitutions unless the user says otherwise. **Stop-and-ask** if the source uses a noticeably distinct easing (overshoot, bounce).
+- **Tailwind first, scoped CSS second.** Prefer `tw-transition`, `tw-duration-*`, `tw-ease-*` utilities; fall back to `<style scoped>` only when a utility doesn't exist for the property or curve.
+- **Don't add a JS animation library.** No `framer-motion` Vue equivalent, no `gsap`, no `motion-vue`. If a component genuinely needs orchestrated numeric animation, write a small composable.
 
-export function useCountUp(target: Ref<number>, active: Ref<boolean>, duration = 500) {
-  // requestAnimationFrame-based tween with easing
-  // Returns reactive ref with current display value
-}
-```
+### 2.5 Timer-Driven Cycles → Composables
+
+`setTimeout`/`setInterval` choreography inside a React `useEffect` should become a composable that owns its timer set and cleans up on unmount. Component files stay declarative; the cycle becomes independently testable.
+
+Guidelines:
+
+- **One owner for timers.** The composable creates timers, holds the references, and clears them on unmount or `stop()`. The component doesn't manage timers directly.
+- **Cancellation is non-negotiable.** Always provide a teardown path and call it from `onBeforeUnmount`. Stale timers firing after unmount are a common source of port bugs.
+- **Expose state, not timers.** Return reactive refs (current step, active flag, etc.) and `start`/`stop` controls — never raw timer IDs.
+- **Test with fake timers.** Use `jest.useFakeTimers()` to assert state transitions at each step boundary without rendering the component.
+- **Make timings injectable.** Pass durations/delays as options with sensible defaults so the cycle can be tuned per consumer (and sped up in tests).
+
+### 2.6 Container-Responsive Sizing
+
+Figma Make outputs **fixed pixel dimensions**. kv-components must be responsive by default, with optional explicit overrides.
+
+Guidelines:
+
+- **Default to 100% width.** Never hardcode a container width into the component.
+- **Mirror existing sizing props.** When a kv-component already implements responsive sizing (e.g. `KvMap` with `aspectRatio` / `height` / `width` props and a `mapDimensions` computed), follow that prop shape so consumers have one mental model.
+- **Decouple internal coordinates from rendered size.** SVG `viewBox`, math keyed off the source's `CONT_W`/`CONT_H` constants, etc. should remain at their natural values; the *container* is what scales. If the source's pan/zoom math is keyed off fixed pixel dimensions, derive those from `getBoundingClientRect()` at runtime.
+- **Use `ResizeObserver` if the container can resize after mount.** Fall back gracefully where it isn't supported.
+- **Aspect-ratio prop, not fixed height.** A numeric `aspectRatio` (width / height) lets the component scale fluidly; explicit `height`/`width` props are escape hatches, not the default path.
 
 ## Phase 3: Component Structure
 
@@ -194,10 +243,13 @@ const { colors } = kvTokensPrimitives;
 
 ### 4.2 Typography
 
-Map Figma Make font references:
-- `Kiva Post Grot:Book` -> `font-weight: 300` (light/book)
-- `Kiva Post Grot:Medium` -> `font-weight: 500` (medium)
-- Font family -> `tw-font-sans` (PostGrotesk)
+The canonical reference for type styling is the [kv-tokens typography skill](../../kv-tokens/docs/skills/typography.md). Consult it before picking a heading element or a text utility; it covers the semantic type scale (`tw-text-display`, `tw-text-headline`, `tw-text-title`, `tw-text-base`, `tw-text-caption`, etc.), heading hierarchy, font pairing, and the HTML / Tailwind mappings.
+
+Quick guidance for a port:
+- **Map Figma Make font references** by intent, not by raw weight: pick the semantic utility (e.g. `tw-text-headline`, `tw-text-title`, `tw-text-label`) that matches the role the text plays. Don't translate `font-weight: 500` into a hand-set numeric weight — pick the utility that the design system says owns "medium" emphasis.
+- **Font family** → `tw-font-sans` (PostGrotesk) by default; only switch when the typography skill calls for `tw-font-serif`.
+- **Heading elements** → follow the heading hierarchy described in the typography skill so any new `<h1>`–`<h6>` usage you introduce uses the correct semantic level for its role.
+- If no existing element default or utility class fits the design, that's a signal to stop and confirm with the design system team — not to author bespoke CSS.
 
 ### 4.3 Spacing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiva/kv-components",
-  "version": "8.11.3",
+  "version": "8.12.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -34,7 +34,7 @@
     "@babel/preset-env": "^7.24.8",
     "@babel/preset-react": "^7.24.7",
     "@babel/preset-typescript": "^7.24.7",
-    "@kiva/kv-tokens": "^4.0.2",
+    "@kiva/kv-tokens": "^4.0.3",
     "@kiva/vite-plugin-vue-lib-css": "^2.0.0",
     "@laynezh/vite-plugin-lib-assets": "^0.6.1",
     "@mdi/js": "^7.4.47",
@@ -125,5 +125,5 @@
     "embla-carousel-fade",
     "popper.js"
   ],
-  "gitHead": "c36f55448e2b6a170321908075aec0176d22ca57"
+  "gitHead": "395f5add0d2149a52dd1e07d7df2da2a321ab11a"
 }