sprintify-ui 0.12.9 → 0.12.11

package/dist/types/components/BaseSignature.vue.d.ts

@@ -0,0 +1,29 @@
+import type { SignatureError } from '@/types';
+type __VLS_Props = {
+    modelValue?: string | null;
+    width?: number;
+    height?: number;
+    disabled?: boolean;
+    showClearButton?: boolean;
+};
+declare function clear(): void;
+declare function isFilled(): boolean;
+declare const _default: import("vue").DefineComponent<__VLS_Props, {
+    clear: typeof clear;
+    isFilled: typeof isFilled;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    error: (error: SignatureError) => any;
+    clear: () => any;
+    "update:modelValue": (value: string | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onError?: ((error: SignatureError) => any) | undefined;
+    onClear?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | null) => any) | undefined;
+}>, {
+    width: number;
+    height: number;
+    disabled: boolean;
+    modelValue: string | null;
+    showClearButton: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/types/components/index.d.ts

@@ -76,6 +76,7 @@ import BaseRadioGroup from './BaseRadioGroup.vue';
 import BaseReadMore from './BaseReadMore.vue';
 import BaseRichText from './BaseRichText.vue';
 import BaseSelect from './BaseSelect.vue';
+import BaseSignature from './BaseSignature.vue';
 import BaseShortcut from './BaseShortcut.vue';
 import BaseSideNavigation from './BaseSideNavigation.vue';
 import BaseSideNavigationItem from './BaseSideNavigationItem.vue';
@@ -107,4 +108,4 @@ import BaseLayoutStacked from './BaseLayoutStacked.vue';
 import BaseLayoutStackedConfigurable from './BaseLayoutStackedConfigurable.vue';
 import BaseLayoutSidebar from './BaseLayoutSidebar.vue';
 import BaseLayoutSidebarConfigurable from './BaseLayoutSidebarConfigurable.vue';
-export { BaseActionButtons, BaseActionItem, BaseAddressForm, BaseAlert, BaseApp, BaseAppDialogs, BaseAppSnackbars, BaseAssign, BaseAutocomplete, BaseAutocompleteFetch, BaseAvatar, BaseAvatarGroup, BaseBadge, BaseBelongsTo, BaseBelongsToFetch, BaseBoolean, BaseBreadcrumbs, BaseButton, BaseButtonGroup, BaseCard, BaseCardRow, BaseCharacterCounter, BaseClipboard, BaseCollapse, BaseColor, BaseContainer, BaseCounter, BaseCropper, BaseCropperModal, BaseDataIterator, BaseDataTable, BaseDatePicker, BaseDateSelect, BaseDraggable, BaseDescriptionList, BaseDescriptionListItem, BaseDialog, BaseDisplayRelativeTime, BaseDropdown, BaseDropdownAutocomplete, BaseEmptyState, BaseField, BaseFieldI18n, BaseFilePicker, BaseFilePickerCrop, BaseFileUploader, BaseForm, BaseGantt, BaseHasMany, BaseHasManyFetch, BaseHeader, BaseIcon, BaseIconPicker, BaseInput, BaseInputLabel, BaseInputPercent, BaseJsonReader, BaseLazy, BaseLoadingCover, BaseMediaItem, BaseMediaLibrary, BaseMediaPreview, BaseMenu, BaseMenuItem, BaseModalCenter, BaseModalSide, BaseNavbar, BaseNavbarItem, BaseNavbarItemContent, BaseNavbarSideItem, BasePagination, BasePanel, BasePassword, BaseProgressCircle, BaseRadioGroup, BaseReadMore, BaseRichText, BaseSelect, BaseShortcut, BaseSideNavigation, BaseSideNavigationItem, BaseSkeleton, BaseStatistic, BaseStepper, BaseStepperItem, BaseSwitch, BaseSystemAlert, BaseTable, BaseTableBody, BaseTableCell, BaseTableHead, BaseTableHeader, BaseTableRow, BaseTabs, BaseTabItem, BaseTagAutocomplete, BaseTagAutocompleteFetch, BaseTableColumn, BaseTextarea, BaseTextareaAutoresize, BaseTimeline, BaseTimelineItem, BaseTimePicker, BaseTooltip, BaseUniqueCode, BaseLayoutStacked, BaseLayoutStackedConfigurable, BaseLayoutSidebar, BaseLayoutSidebarConfigurable, };
+export { BaseActionButtons, BaseActionItem, BaseAddressForm, BaseAlert, BaseApp, BaseAppDialogs, BaseAppSnackbars, BaseAssign, BaseAutocomplete, BaseAutocompleteFetch, BaseAvatar, BaseAvatarGroup, BaseBadge, BaseBelongsTo, BaseBelongsToFetch, BaseBoolean, BaseBreadcrumbs, BaseButton, BaseButtonGroup, BaseCard, BaseCardRow, BaseCharacterCounter, BaseClipboard, BaseCollapse, BaseColor, BaseContainer, BaseCounter, BaseCropper, BaseCropperModal, BaseDataIterator, BaseDataTable, BaseDatePicker, BaseDateSelect, BaseDraggable, BaseDescriptionList, BaseDescriptionListItem, BaseDialog, BaseDisplayRelativeTime, BaseDropdown, BaseDropdownAutocomplete, BaseEmptyState, BaseField, BaseFieldI18n, BaseFilePicker, BaseFilePickerCrop, BaseFileUploader, BaseForm, BaseGantt, BaseHasMany, BaseHasManyFetch, BaseHeader, BaseIcon, BaseIconPicker, BaseInput, BaseInputLabel, BaseInputPercent, BaseJsonReader, BaseLazy, BaseLoadingCover, BaseMediaItem, BaseMediaLibrary, BaseMediaPreview, BaseMenu, BaseMenuItem, BaseModalCenter, BaseModalSide, BaseNavbar, BaseNavbarItem, BaseNavbarItemContent, BaseNavbarSideItem, BasePagination, BasePanel, BasePassword, BaseProgressCircle, BaseRadioGroup, BaseReadMore, BaseRichText, BaseSelect, BaseSignature, BaseShortcut, BaseSideNavigation, BaseSideNavigationItem, BaseSkeleton, BaseStatistic, BaseStepper, BaseStepperItem, BaseSwitch, BaseSystemAlert, BaseTable, BaseTableBody, BaseTableCell, BaseTableHead, BaseTableHeader, BaseTableRow, BaseTabs, BaseTabItem, BaseTagAutocomplete, BaseTagAutocompleteFetch, BaseTableColumn, BaseTextarea, BaseTextareaAutoresize, BaseTimeline, BaseTimelineItem, BaseTimePicker, BaseTooltip, BaseUniqueCode, BaseLayoutStacked, BaseLayoutStackedConfigurable, BaseLayoutSidebar, BaseLayoutSidebarConfigurable, };

package/dist/types/index.d.ts

@@ -83,6 +83,9 @@ declare const messages: {
             select_all: string;
             select_an_item: string;
             select_an_option: string;
+            signature_load_failed: string;
+            signature_must_be_png: string;
+            signature_pad: string;
             success: string;
             the_file_size_must_not_exceed_x: string;
             the_file_type_is_invalid: string;
@@ -186,6 +189,9 @@ declare const messages: {
             select_all: string;
             select_an_item: string;
             select_an_option: string;
+            signature_load_failed: string;
+            signature_must_be_png: string;
+            signature_pad: string;
             success: string;
             the_file_size_must_not_exceed_x: string;
             the_file_type_is_invalid: string;

package/dist/types/types/index.d.ts

@@ -9,6 +9,11 @@ import { ToolbarOption } from './ToolbarOption';
 export type Locales = {
     [locale: string]: string;
 };
+export type SignatureErrorCode = 'invalid_png' | 'load_failed';
+export interface SignatureError {
+    code: SignatureErrorCode;
+    message: string;
+}
 export declare enum Method {
     post = "post",
     put = "put",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprintify-ui",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "type": "module",
   "scripts": {
     "generate-llm-txt": "node scripts/generate-llm-txt.js",

package/src/components/BaseLayoutSidebar.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="min-h-full">
+  <div class="min-h-full base-layout-sidebar">
     <TransitionRoot
       as="template"
       :show="showMobileMenu"
@@ -109,7 +109,7 @@
         </BaseSystemAlert>
 
         <div
-          class="flex bg-white"
+          class="flex bg-white base-layout-sidebar-navbar"
           :style="{ height: navbarHeight + 'px' }"
         >
           <button

package/src/components/BaseSignature.mdx

@@ -0,0 +1,119 @@
+import { Canvas, Controls, Meta, Primary } from '@storybook/addon-docs/blocks';
+
+import * as BaseSignatureStories from './BaseSignature.stories';
+
+<Meta of={BaseSignatureStories} />
+
+# BaseSignature
+
+## Introduction
+
+`BaseSignature` is a responsive signature pad for mouse, touch, and pen input. It smooths pointer movement with quadratic curves, varies stroke width according to pointer speed, and uses pen pressure when the device provides it.
+
+The component uses a canvas for fluid input and always emits a white-background PNG Data URL. Existing PNG signatures can be loaded through `v-model` and extended with new strokes.
+
+<Primary />
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BaseSignature } from 'sprintify-ui';
+
+const signature = ref<string | null>(null);
+</script>
+
+<template>
+  <BaseSignature v-model="signature" />
+</template>
+```
+
+`update:modelValue` is emitted after each completed stroke. Clearing the pad emits `update:modelValue` with `null`, followed by the `clear` event.
+
+## Existing signatures and resizing
+
+Only complete PNG Data URLs are accepted, for example `data:image/png;base64,...`. The image is inspected to find its visible, non-white pixels. That content is then scaled proportionally, centered, and rendered with 8% horizontal and vertical padding.
+
+This content-aware approach handles input images that are larger, smaller, wider, or taller than the signature pad without cropping or distortion.
+
+<Canvas of={BaseSignatureStories.ExistingSignature} />
+
+The same signature also adapts to a smaller pad:
+
+<Canvas of={BaseSignatureStories.Compact} />
+
+Loading a value only renders it. It does not emit a new `update:modelValue` event. Once another stroke is added, the imported image and new stroke are flattened into a PNG matching the current canvas.
+
+## PNG validation
+
+JPEG, WebP, SVG, malformed Data URLs, and invalid PNG payloads are rejected. The component displays a translated error and emits an `error` event with a stable code and translated message.
+
+<Canvas of={BaseSignatureStories.InvalidPng} />
+
+## Disabled state
+
+The `disabled` prop prevents pointer input and disables the built-in clear button. Exposed methods remain available to the parent component.
+
+<Canvas of={BaseSignatureStories.Disabled} />
+
+## Props
+
+<Controls />
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string \| null` | `null` | Complete PNG Data URL containing the current signature. |
+| `width` | `number` | `400` | Maximum visual width of the signature pad in pixels. The pad can shrink with its parent. |
+| `height` | `number` | `180` | Visual height used to determine the pad aspect ratio. |
+| `disabled` | `boolean` | `false` | Prevents drawing and clearing through the built-in button. |
+| `showClearButton` | `boolean` | `true` | Shows or hides the built-in translated clear button. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string \| null` | Emits a PNG Data URL after a stroke, or `null` after clearing. |
+| `clear` | — | Emitted after the signature is cleared. |
+| `error` | `SignatureError` | Emitted when the input is not a valid PNG or cannot be loaded. |
+
+```ts
+type SignatureErrorCode = 'invalid_png' | 'load_failed';
+
+interface SignatureError {
+  code: SignatureErrorCode;
+  message: string;
+}
+```
+
+## Exposed methods
+
+| Method | Return type | Description |
+|--------|-------------|-------------|
+| `isFilled()` | `boolean` | Returns whether the pad contains visible signature pixels. A white or transparent PNG is considered empty. |
+| `clear()` | `void` | Clears the pad and emits both `update:modelValue` and `clear`. |
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BaseSignature } from 'sprintify-ui';
+
+const signaturePad = ref<InstanceType<typeof BaseSignature> | null>(null);
+
+function validateSignature() {
+  return signaturePad.value?.isFilled() ?? false;
+}
+
+function clearSignature() {
+  signaturePad.value?.clear();
+}
+</script>
+
+<template>
+  <BaseSignature ref="signaturePad" :show-clear-button="false" />
+</template>
+```
+
+## Canvas rather than SVG
+
+Canvas is used because it offers direct, efficient Pointer Events support and predictable PNG export for mouse, touch, and pressure-sensitive pens. Stroke points are smoothed while drawing, but the public input and output remain raster PNGs. SVG would be preferable only when preserving editable vector paths is a requirement.

package/src/components/BaseSignature.stories.js

@@ -0,0 +1,232 @@
+import { computed, nextTick, onMounted, ref } from "vue";
+import { BaseButton, BaseSignature } from ".";
+
+function createDemoSignature(width = 960, height = 220) {
+  const canvas = document.createElement("canvas");
+  const context = canvas.getContext("2d");
+
+  canvas.width = width;
+  canvas.height = height;
+
+  context.fillStyle = "#ffffff";
+  context.fillRect(0, 0, width, height);
+  context.strokeStyle = "#000000";
+  context.lineCap = "round";
+  context.lineJoin = "round";
+  context.lineWidth = 8;
+
+  context.beginPath();
+  context.moveTo(145, 145);
+  context.bezierCurveTo(225, 25, 250, 190, 330, 72);
+  context.bezierCurveTo(350, 42, 345, 165, 405, 122);
+  context.bezierCurveTo(455, 86, 475, 58, 452, 132);
+  context.bezierCurveTo(438, 178, 515, 64, 550, 120);
+  context.bezierCurveTo(575, 160, 620, 70, 648, 119);
+  context.bezierCurveTo(680, 174, 735, 82, 790, 125);
+  context.stroke();
+
+  context.lineWidth = 5;
+  context.beginPath();
+  context.moveTo(105, 164);
+  context.bezierCurveTo(310, 194, 590, 155, 835, 153);
+  context.stroke();
+
+  return canvas.toDataURL("image/png");
+}
+
+export default {
+  title: "Form/BaseSignature",
+  component: BaseSignature,
+  args: {
+    modelValue: null,
+    width: 400,
+    height: 180,
+    disabled: false,
+    showClearButton: true,
+  },
+  argTypes: {
+    modelValue: {
+      control: false,
+      description: "A PNG Data URL, or null when the signature is empty.",
+    },
+    width: {
+      control: { type: "number", min: 1 },
+      description: "Maximum visual width of the signature pad in pixels.",
+    },
+    height: {
+      control: { type: "number", min: 1 },
+      description: "Visual height of the signature pad in pixels.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "Prevents drawing and clearing from the built-in button.",
+    },
+    showClearButton: {
+      control: "boolean",
+      description: "Shows the built-in clear button below the pad.",
+    },
+    "update:modelValue": {
+      action: "update:modelValue",
+      table: { category: "Events" },
+    },
+    clear: {
+      action: "clear",
+      table: { category: "Events" },
+    },
+    error: {
+      action: "error",
+      table: { category: "Events" },
+    },
+  },
+};
+
+const InteractiveTemplate = (args) => ({
+  components: { BaseButton, BaseSignature },
+  setup() {
+    const signature = ref(args.modelValue);
+    const signatureComponent = ref(null);
+    const filled = ref(false);
+    const lastError = ref(null);
+    const base64Preview = computed(() => {
+      if (!signature.value) return "null";
+
+      const size = Math.ceil(signature.value.length / 1024);
+
+      return `${signature.value.slice(0, 54)}… (${size} KiB)`;
+    });
+
+    function updateFilledState() {
+      filled.value = signatureComponent.value?.isFilled() ?? false;
+    }
+
+    function updateSignature(value) {
+      signature.value = value;
+      nextTick(updateFilledState);
+    }
+
+    function clearFromOutside() {
+      signatureComponent.value?.clear();
+      nextTick(updateFilledState);
+    }
+
+    function onError(error) {
+      lastError.value = error;
+    }
+
+    return {
+      args,
+      base64Preview,
+      clearFromOutside,
+      filled,
+      lastError,
+      onError,
+      signature,
+      signatureComponent,
+      updateFilledState,
+      updateSignature,
+    };
+  },
+  template: `
+    <div class="space-y-5">
+      <BaseSignature
+        ref="signatureComponent"
+        v-bind="args"
+        :model-value="signature"
+        @update:model-value="updateSignature"
+        @clear="updateFilledState"
+        @error="onError"
+      />
+
+      <div class="flex flex-wrap items-center gap-3">
+        <BaseButton
+          type="button"
+          size="sm"
+          color="secondary-outline"
+          @click="clearFromOutside"
+        >
+          Clear from the parent
+        </BaseButton>
+        <span class="text-sm text-slate-600">
+          isFilled(): <strong>{{ filled }}</strong>
+        </span>
+      </div>
+
+      <div class="max-w-2xl rounded-md bg-slate-900 p-3 font-mono text-xs text-slate-100">
+        {{ base64Preview }}
+      </div>
+
+      <div
+        v-if="lastError"
+        class="max-w-2xl rounded-md bg-red-50 p-3 text-sm text-red-700"
+      >
+        {{ lastError.code }} — {{ lastError.message }}
+      </div>
+    </div>
+  `,
+});
+
+export const Demo = InteractiveTemplate.bind({});
+
+const ExistingSignatureTemplate = (args) => ({
+  components: { BaseSignature },
+  setup() {
+    const signature = ref(null);
+
+    onMounted(() => {
+      signature.value = createDemoSignature();
+    });
+
+    return { args, signature };
+  },
+  template: `
+    <div class="space-y-3">
+      <BaseSignature v-bind="args" v-model="signature" />
+      <p class="max-w-lg text-sm text-slate-600">
+        This 960 × 220 PNG is cropped to its visible pixels, scaled proportionally,
+        centered, and rendered with balanced padding.
+      </p>
+    </div>
+  `,
+});
+
+export const ExistingSignature = ExistingSignatureTemplate.bind({});
+ExistingSignature.args = {
+  width: 400,
+  height: 180,
+};
+
+export const Compact = ExistingSignatureTemplate.bind({});
+Compact.args = {
+  width: 280,
+  height: 120,
+};
+
+export const Disabled = ExistingSignatureTemplate.bind({});
+Disabled.args = {
+  disabled: true,
+};
+
+const InvalidPngTemplate = (args) => ({
+  components: { BaseSignature },
+  setup() {
+    const signature = ref("data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2Q==");
+    const emittedError = ref(null);
+
+    return { args, emittedError, signature };
+  },
+  template: `
+    <div class="space-y-3">
+      <BaseSignature
+        v-bind="args"
+        v-model="signature"
+        @error="emittedError = $event"
+      />
+      <pre
+        v-if="emittedError"
+        class="max-w-lg rounded-md bg-red-50 p-3 text-xs text-red-700"
+      >{{ emittedError }}</pre>
+    </div>
+  `,
+});
+
+export const InvalidPng = InvalidPngTemplate.bind({});