@gcsa/console-vue 0.1.0

package/src/components/GcsaTree.vue

@@ -0,0 +1,56 @@
+<template>
+  <div class="gcsa-tree" role="tree" :aria-multiselectable="multiple">
+    <div v-if="!nodes.length" class="gcsa-tree__empty" role="status">{{ messages.emptyDefault }}</div>
+    <TreeNode v-for="(node, index) in nodes" :key="node.key" :node="node" :depth="0" :position="index + 1" :set-size="nodes.length" :expanded-keys="expandedKeys" :selected-keys="selectedKeys" :multiple="multiple" @toggle="toggleExpanded" @select="selectNode" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, defineComponent, h, ref, watch, type PropType } from 'vue';
+import type { GcsaTreeNode, GcsaTreeProps } from '../types/componentProps';
+import GcsaIcon from './GcsaIcon.vue';
+import { useGcsaLocaleMessages } from '../composables/useGcsaLocale';
+
+const messages = useGcsaLocaleMessages();
+
+const props = withDefaults(defineProps<GcsaTreeProps>(), { nodes: () => [], multiple: false });
+const emit = defineEmits<{ 'update:expandedKeys': [keys: string[]]; 'update:selectedKeys': [keys: string[]]; select: [node: GcsaTreeNode] }>();
+const internalExpandedKeys = ref<string[]>(props.expandedKeys ?? []);
+const internalSelectedKeys = ref<string[]>(props.selectedKeys ?? []);
+const expandedKeys = computed(() => props.expandedKeys ?? internalExpandedKeys.value);
+const selectedKeys = computed(() => props.selectedKeys ?? internalSelectedKeys.value);
+watch(() => props.expandedKeys, value => { if (value) internalExpandedKeys.value = value; });
+watch(() => props.selectedKeys, value => { if (value) internalSelectedKeys.value = value; });
+function toggleExpanded(key: string) {
+  const next = expandedKeys.value.includes(key) ? expandedKeys.value.filter(value => value !== key) : [...expandedKeys.value, key];
+  if (props.expandedKeys === undefined) internalExpandedKeys.value = next;
+  emit('update:expandedKeys', next);
+}
+function selectNode(node: GcsaTreeNode) {
+  if (node.disabled) return;
+  const next = props.multiple ? (selectedKeys.value.includes(node.key) ? selectedKeys.value.filter(value => value !== node.key) : [...selectedKeys.value, node.key]) : [node.key];
+  if (props.selectedKeys === undefined) internalSelectedKeys.value = next;
+  emit('update:selectedKeys', next);
+  emit('select', node);
+}
+
+const TreeNode = defineComponent({
+  name: 'GcsaTreeNode',
+  props: { node: { type: Object as PropType<GcsaTreeNode>, required: true }, depth: { type: Number, required: true }, position: { type: Number, required: true }, setSize: { type: Number, required: true }, expandedKeys: { type: Array as PropType<string[]>, required: true }, selectedKeys: { type: Array as PropType<string[]>, required: true }, multiple: { type: Boolean, required: true } },
+  emits: ['toggle', 'select'],
+  setup(nodeProps, { emit: nodeEmit }) {
+    const hasChildren = computed(() => Boolean(nodeProps.node.children?.length));
+    const expanded = computed(() => nodeProps.expandedKeys.includes(nodeProps.node.key));
+    const selected = computed(() => nodeProps.selectedKeys.includes(nodeProps.node.key));
+    const childrenId = `gcsa-tree-children-${nodeProps.node.key}`;
+    return (): ReturnType<typeof h> => h('div', { class: 'gcsa-tree__branch', role: 'treeitem', 'aria-level': nodeProps.depth + 1, 'aria-posinset': nodeProps.position, 'aria-setsize': nodeProps.setSize, 'aria-expanded': hasChildren.value ? expanded.value : undefined }, [
+      h('div', { class: 'gcsa-tree__node', style: { paddingInlineStart: `${nodeProps.depth * 20 + 8}px` }, 'data-selected': selected.value || undefined, 'data-expanded': hasChildren.value ? expanded.value : undefined, 'data-leaf': !hasChildren.value || undefined }, [
+        hasChildren.value ? h('button', { type: 'button', class: 'gcsa-tree__toggle gcsa-focus-ring', 'aria-label': expanded.value ? 'Collapse' : 'Expand', 'aria-expanded': expanded.value, 'aria-controls': childrenId, onClick: () => nodeEmit('toggle', nodeProps.node.key) }, [h(GcsaIcon, { name: 'chevronDown', size: 'sm', class: ['gcsa-tree__caret', expanded.value && 'gcsa-tree__caret--expanded'] })]) : h('span', { class: 'gcsa-tree__spacer' }),
+        h('button', { type: 'button', class: 'gcsa-tree__label gcsa-focus-ring', disabled: nodeProps.node.disabled, onClick: () => nodeEmit('select', nodeProps.node) }, nodeProps.node.label),
+        hasChildren.value && !expanded.value ? h('span', { class: 'gcsa-tree__summary', 'aria-label': `${nodeProps.node.children!.length} 项` }, `${nodeProps.node.children!.length} 项`) : null
+      ]),
+      hasChildren.value && expanded.value ? h('div', { id: childrenId, class: 'gcsa-tree__children', role: 'group' }, nodeProps.node.children!.map((child, index) => h(TreeNode, { node: child, depth: nodeProps.depth + 1, position: index + 1, setSize: nodeProps.node.children!.length, expandedKeys: nodeProps.expandedKeys, selectedKeys: nodeProps.selectedKeys, multiple: nodeProps.multiple, onToggle: (key: string) => nodeEmit('toggle', key), onSelect: (childNode: GcsaTreeNode) => nodeEmit('select', childNode) }))) : null
+    ]);
+  }
+});
+</script>

package/src/components/GcsaTypography.vue

@@ -0,0 +1,28 @@
+<template>
+  <div class="gcsa-ui-surface" :class="classes">
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+import type { GcsaTypographyProps } from '../types/componentProps';
+
+defineOptions({ name: 'GcsaTypography' });
+
+const props = withDefaults(
+  defineProps<GcsaTypographyProps>(),
+  {
+    variant: 'text',
+    level: 3
+  }
+);
+
+const classes = computed(() => {
+  if (props.variant === 'title') {
+    return `gcsa-typography gcsa-typography-title gcsa-typography-title--l${props.level}`;
+  }
+  return 'gcsa-typography gcsa-typography-text';
+});
+</script>

package/src/components/GcsaUpload.vue

@@ -0,0 +1,154 @@
+<template>
+  <div class="gcsa-upload" :class="{ 'gcsa-upload--disabled': disabled, 'gcsa-upload--dragging': dragging }">
+    <input
+      ref="inputRef"
+      type="file"
+      class="gcsa-upload__native"
+      :accept="accept"
+      :multiple="multiple"
+      :webkitdirectory="directory || undefined"
+      :disabled="disabled"
+      @change="onNativeChange"
+    />
+    <div
+      class="gcsa-upload__dropzone"
+      role="button"
+      tabindex="0"
+      @click="openPicker"
+      @keydown.enter.prevent="openPicker"
+      @keydown.space.prevent="openPicker"
+      @dragenter.prevent="onDragEnter"
+      @dragover.prevent="onDragEnter"
+      @dragleave.prevent="dragging = false"
+      @drop.prevent="onDrop"
+    >
+      <span class="gcsa-upload__icon" aria-hidden="true">
+        <GcsaIcon name="plus" />
+      </span>
+      <span class="gcsa-upload__title">{{ resolvedButtonLabel }}</span>
+      <p v-if="resolvedHint" class="gcsa-upload__hint">{{ resolvedHint }}</p>
+    </div>
+    <ul v-if="files.length" class="gcsa-upload__list">
+      <li v-for="(file, index) in files" :key="`${file.name}-${index}`" class="gcsa-upload__item">
+        <span class="gcsa-upload__name">{{ file.name }}</span>
+        <span class="gcsa-upload__size">{{ formatSize(file.size) }}</span>
+        <span v-if="statuses.get(file) === 'uploading'" class="gcsa-upload__status" role="status">{{ resolvedUploadingLabel }} {{ progress.get(file) ?? 0 }}%</span>
+        <span v-else-if="statuses.get(file) === 'error'" class="gcsa-upload__status gcsa-upload__status--error" role="alert">{{ resolvedUploadErrorLabel }}</span>
+        <div v-if="statuses.get(file) === 'uploading'" class="gcsa-upload__progress" aria-hidden="true"><span :style="{ width: `${progress.get(file) ?? 0}%` }" /></div>
+        <button v-if="statuses.get(file) === 'error'" type="button" class="gcsa-upload__retry gcsa-focus-ring" :disabled="disabled" @click="uploadFile(file)">{{ resolvedRetryLabel }}</button>
+        <button
+          type="button"
+          class="gcsa-upload__remove gcsa-focus-ring"
+          :disabled="disabled"
+          :aria-label="messages.uploadRemoveFile"
+          @click="removeAt(index)"
+        >
+          {{ messages.remove }}
+        </button>
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import type { GcsaUploadProps } from '../types/componentProps';
+import GcsaIcon from './GcsaIcon.vue';
+import { useGcsaLocaleMessages } from '../composables/useGcsaLocale';
+
+defineOptions({ name: 'GcsaUpload' });
+
+const props = withDefaults(
+  defineProps<GcsaUploadProps>(),
+  {
+    files: () => [],
+    multiple: false,
+    drag: false,
+    directory: false
+  }
+);
+
+const messages = useGcsaLocaleMessages();
+const resolvedButtonLabel = computed(() => props.buttonLabel ?? messages.value.uploadSelectFile);
+const resolvedHint = computed(() => props.hint || (props.drag ? resolvedDragLabel.value : undefined));
+const resolvedDragLabel = computed(() => props.dragLabel ?? messages.value.uploadDragHint);
+const resolvedUploadingLabel = computed(() => props.uploadingLabel ?? messages.value.uploadUploading);
+const resolvedUploadErrorLabel = computed(() => props.uploadErrorLabel ?? messages.value.uploadFailed);
+const resolvedRetryLabel = computed(() => props.retryLabel ?? messages.value.uploadRetry);
+
+const emit = defineEmits<{
+  'update:files': [files: File[]];
+  'upload-start': [file: File];
+  'upload-success': [file: File];
+  'upload-error': [details: { file: File; error: unknown }];
+}>();
+
+const inputRef = ref<HTMLInputElement | null>(null);
+const dragging = ref(false);
+const statuses = ref(new Map<File, 'uploading' | 'success' | 'error'>());
+const progress = ref(new Map<File, number>());
+
+function openPicker() {
+  inputRef.value?.click();
+}
+
+function onDragEnter() {
+  if (!props.drag || props.disabled) return;
+  dragging.value = true;
+}
+
+function onNativeChange(event: Event) {
+  const input = event.target as HTMLInputElement;
+  const picked = Array.from(input.files ?? []);
+  input.value = '';
+  if (!picked.length) return;
+
+  acceptFiles(picked);
+}
+
+function onDrop(event: DragEvent) {
+  dragging.value = false;
+  if (!props.drag || props.disabled) return;
+  acceptFiles(Array.from(event.dataTransfer?.files ?? []));
+}
+
+function acceptFiles(picked: File[]) {
+  if (!picked.length || props.disabled) return;
+  const valid = props.maxSize == null ? picked : picked.filter(file => file.size <= props.maxSize!);
+  let next = props.multiple ? [...props.files, ...valid] : valid.slice(0, 1);
+  if (props.maxCount != null) next = next.slice(0, props.maxCount);
+  emit('update:files', next);
+  if (props.upload) next.filter(file => valid.includes(file)).forEach(uploadFile);
+}
+
+async function uploadFile(file: File) {
+  if (!props.upload) return;
+  statuses.value = new Map(statuses.value).set(file, 'uploading');
+  progress.value = new Map(progress.value).set(file, 0);
+  emit('upload-start', file);
+  try {
+    await props.upload(file, percent => {
+      const next = Math.max(0, Math.min(100, Math.round(percent)));
+      progress.value = new Map(progress.value).set(file, next);
+      props.onProgress?.(file, next);
+    });
+    statuses.value = new Map(statuses.value).set(file, 'success');
+    progress.value = new Map(progress.value).set(file, 100);
+    emit('upload-success', file);
+  } catch (error) {
+    statuses.value = new Map(statuses.value).set(file, 'error');
+    emit('upload-error', { file, error });
+  }
+}
+
+function removeAt(index: number) {
+  const next = props.files.filter((_, i) => i !== index);
+  emit('update:files', next);
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+</script>

package/src/components/gcsaDataTableTypes.ts

@@ -0,0 +1,18 @@
+export type GcsaDataTableApi<T extends Record<string, unknown>> = {
+  clearSorting: () => void;
+  clearFilters: () => void;
+  clearSelection: () => void;
+  clearExpanded: () => void;
+  setRowSelected: (key: string, selected?: boolean) => void;
+  setRowExpanded: (key: string, expanded?: boolean) => Promise<void>;
+  clearSort: () => void;
+  clearFilter: (columnKeys?: string | string[]) => void;
+  sort: (prop: string, order: 'ascending' | 'descending' | null) => void;
+  toggleRowSelection: (row: T, selected?: boolean) => void;
+  toggleAllSelection: () => void;
+  toggleRowExpansion: (row: T, expanded?: boolean) => Promise<void>;
+  setCurrentRow: (row?: T) => void;
+  getSelectionRows: () => T[];
+  setScrollTop: (top: number) => void;
+  scrollTo: (options: ScrollToOptions | number, y?: number) => void;
+};

package/src/composables/gcsaFormTypes.ts

@@ -0,0 +1,30 @@
+import type { FormApi } from '@tanstack/vue-form';
+import type { useForm } from '@tanstack/vue-form';
+
+export type GcsaFormValues = Record<string, unknown>;
+
+type VueUseFormReturn = ReturnType<typeof useForm>;
+
+/**
+ * Form instance used by GcsaForm / GcsaFormField.
+ * Validator generics are relaxed so schema-backed forms remain assignable.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GcsaFormApi = FormApi<
+  GcsaFormValues,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+> &
+  Pick<
+    VueUseFormReturn,
+    'Field' | 'FormGroup' | 'useSelector' | 'useStore' | 'Subscribe'
+  >;

package/src/composables/useDocumentThemeSync.ts

@@ -0,0 +1,6 @@
+import type { InjectionKey } from 'vue';
+
+/** Docs / app may provide this to restore document theme after ConfigProvider unmounts. */
+export const GCSA_RESTORE_DOCUMENT_THEME_KEY: InjectionKey<() => void> = Symbol(
+  'gcsa-restore-document-theme'
+);

package/src/composables/useGcsaComponentSize.ts

@@ -0,0 +1,30 @@
+import { computed, inject, provide, toValue, type ComputedRef, type InjectionKey, type MaybeRefOrGetter } from 'vue';
+import {
+  GCSA_DEFAULT_COMPONENT_SIZE,
+  resolveGcsaButtonSize,
+  resolveGcsaComponentSize,
+  type GcsaButtonSize,
+  type GcsaComponentSize
+} from '@gcsa/console-core';
+
+export const GCSA_COMPONENT_SIZE_KEY: InjectionKey<ComputedRef<GcsaComponentSize>> =
+  Symbol('gcsa-component-size');
+
+export function useGcsaComponentSizeConfig(): GcsaComponentSize {
+  const configSize = inject(GCSA_COMPONENT_SIZE_KEY);
+  return configSize?.value ?? GCSA_DEFAULT_COMPONENT_SIZE;
+}
+
+export function useGcsaComponentSize(propSize?: MaybeRefOrGetter<GcsaComponentSize | undefined>) {
+  const configSize = useGcsaComponentSizeConfig();
+  return computed(() => resolveGcsaComponentSize(toValue(propSize), configSize));
+}
+
+export function useGcsaButtonSize(propSize?: MaybeRefOrGetter<GcsaButtonSize | undefined>) {
+  const configSize = useGcsaComponentSizeConfig();
+  return computed(() => resolveGcsaButtonSize(toValue(propSize), configSize));
+}
+
+export function provideGcsaComponentSize(size: ComputedRef<GcsaComponentSize>) {
+  provide(GCSA_COMPONENT_SIZE_KEY, size);
+}

package/src/composables/useGcsaFormField.ts

@@ -0,0 +1,49 @@
+import type { FieldApi } from '@tanstack/vue-form';
+
+/** TanStack FieldApi with relaxed generics for field binding helpers. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GcsaAnyFieldApi = FieldApi<any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any>;
+
+export function gcsaTextFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    modelValue: field.state.value as string,
+    invalid: Boolean(error),
+    onBlur: () => field.handleBlur(),
+    'onUpdate:modelValue': (value: string) => field.handleChange(value)
+  };
+}
+
+export function gcsaBooleanFieldBindings(field: GcsaAnyFieldApi) {
+  return {
+    modelValue: Boolean(field.state.value),
+    'onUpdate:modelValue': (value: boolean) => field.handleChange(value)
+  };
+}
+
+export function gcsaRadioFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    modelValue: (field.state.value as string) ?? '',
+    invalid: Boolean(error),
+    'onUpdate:modelValue': (value: string) => field.handleChange(value)
+  };
+}
+
+export function gcsaNumberFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    modelValue: field.state.value as number | null,
+    invalid: Boolean(error),
+    onBlur: () => field.handleBlur(),
+    'onUpdate:modelValue': (value: number | null) => field.handleChange(value)
+  };
+}
+
+export function gcsaFieldError(field: GcsaAnyFieldApi) {
+  return field.state.meta.errors[0] as string | undefined;
+}
+
+export function gcsaFieldInvalid(field: GcsaAnyFieldApi) {
+  return field.state.meta.errors.length > 0;
+}

package/src/composables/useGcsaFormSchema.ts

@@ -0,0 +1,6 @@
+import type { InjectionKey } from 'vue';
+import type { ZodObject, ZodTypeAny } from 'zod';
+
+export const GCSA_FORM_SCHEMA_KEY: InjectionKey<ZodObject<Record<string, ZodTypeAny>>> = Symbol(
+  'gcsa-form-schema'
+);

package/src/composables/useGcsaLocale.ts

@@ -0,0 +1,18 @@
+import { computed, inject, type ComputedRef } from 'vue';
+import {
+  GCSA_DEFAULT_LOCALE,
+  getGcsaLocaleMessages,
+  type GcsaConsoleLocale
+} from '@gcsa/console-core';
+
+export const GCSA_LOCALE_KEY = Symbol('gcsa-locale');
+
+export function useGcsaLocale(): ComputedRef<GcsaConsoleLocale> {
+  const locale = inject<ComputedRef<GcsaConsoleLocale> | null>(GCSA_LOCALE_KEY, null);
+  return computed(() => locale?.value ?? GCSA_DEFAULT_LOCALE);
+}
+
+export function useGcsaLocaleMessages() {
+  const locale = useGcsaLocale();
+  return computed(() => getGcsaLocaleMessages(locale.value));
+}

package/src/composables/useGcsaMessage.ts

@@ -0,0 +1,10 @@
+import { inject } from 'vue';
+import { GCSA_MESSAGE_KEY, type GcsaMessageApi } from './useMessage';
+
+export function useGcsaMessage(): GcsaMessageApi {
+  const api = inject(GCSA_MESSAGE_KEY);
+  if (!api) {
+    throw new Error('useGcsaMessage must be used within GcsaConfigProvider');
+  }
+  return api;
+}

package/src/composables/useGcsaPopupZIndex.ts

@@ -0,0 +1,24 @@
+import { ref, type Ref } from 'vue';
+import { useGcsaZIndex } from './useGcsaZIndex';
+
+export function useGcsaPopupZIndex(): {
+  zIndex: Ref<number | undefined>;
+  claimZIndex: () => number;
+  onOpenChange: (open: boolean) => void;
+} {
+  const { nextZIndex } = useGcsaZIndex();
+  const zIndex = ref<number>();
+
+  function claimZIndex() {
+    zIndex.value = nextZIndex();
+    return zIndex.value;
+  }
+
+  function onOpenChange(open: boolean) {
+    if (open) {
+      claimZIndex();
+    }
+  }
+
+  return { zIndex, claimZIndex, onOpenChange };
+}

package/src/composables/useGcsaTextCount.ts

@@ -0,0 +1,48 @@
+import { computed, type MaybeRefOrGetter, toValue } from 'vue';
+
+export type GcsaTextCountFormatter = (info: {
+  value: string;
+  count: number;
+  maxLength?: number;
+}) => string;
+
+export function useGcsaTextCount(options: {
+  modelValue: MaybeRefOrGetter<string | undefined>;
+  maxLength?: MaybeRefOrGetter<number | undefined>;
+  showCount?: MaybeRefOrGetter<boolean | undefined>;
+  formatter?: GcsaTextCountFormatter;
+}) {
+  const showCounter = computed(() => {
+    const max = toValue(options.maxLength);
+    const explicit = toValue(options.showCount);
+
+    if (explicit === true) return true;
+    if (explicit === false) return false;
+    return max != null;
+  });
+
+  const count = computed(() => toValue(options.modelValue)?.length ?? 0);
+
+  const countText = computed(() => {
+    const value = toValue(options.modelValue) ?? '';
+    const current = count.value;
+    const max = toValue(options.maxLength);
+
+    if (options.formatter) {
+      return options.formatter({ value, count: current, maxLength: max });
+    }
+
+    if (max != null) {
+      return `${current}/${max}`;
+    }
+
+    return String(current);
+  });
+
+  const isNearLimit = computed(() => {
+    const max = toValue(options.maxLength);
+    return max != null && count.value >= max * 0.9;
+  });
+
+  return { showCounter, count, countText, isNearLimit };
+}

package/src/composables/useGcsaTheme.ts

@@ -0,0 +1,9 @@
+import { inject, type ComputedRef } from 'vue';
+import type { GcsaConsoleTheme } from '@gcsa/console-core';
+
+export const GCSA_THEME_KEY = Symbol('gcsa-theme');
+
+export function useGcsaTheme(): GcsaConsoleTheme {
+  const theme = inject<ComputedRef<GcsaConsoleTheme>>(GCSA_THEME_KEY);
+  return theme?.value ?? 'dark';
+}

package/src/composables/useGcsaZIndex.ts

@@ -0,0 +1,62 @@
+import { inject, provide, type InjectionKey } from 'vue';
+
+export type GcsaZIndexApi = {
+  next: () => number;
+};
+
+export const GCSA_Z_INDEX_KEY: InjectionKey<GcsaZIndexApi> = Symbol('gcsa-z-index');
+
+const FALLBACK_INITIAL = 2000;
+const FALLBACK_TOAST = 1300;
+const Z_INDEX_STEP = 2;
+
+function readCssZIndex(token: string, fallback: number): number {
+  if (typeof document === 'undefined') return fallback;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(token).trim();
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function readToastZIndex(): number {
+  const toast = readCssZIndex('--gcsa-z-toast', Number.NaN);
+  const overlay = readCssZIndex('--z-overlay-toast', Number.NaN);
+  const candidates = [toast, overlay, FALLBACK_TOAST].filter(value => Number.isFinite(value));
+  return Math.max(...candidates);
+}
+
+function createZIndexApi(initial: number): GcsaZIndexApi {
+  let current = initial;
+  return {
+    next() {
+      current += Z_INDEX_STEP;
+      return current;
+    }
+  };
+}
+
+function readInitialZIndex(): number {
+  if (typeof document === 'undefined') return FALLBACK_INITIAL;
+  const root = document.documentElement;
+  const initial = getComputedStyle(root).getPropertyValue('--gcsa-z-index-initial').trim();
+  const parsedInitial = Number.parseInt(initial, 10);
+  if (Number.isFinite(parsedInitial)) return parsedInitial;
+  const modal = getComputedStyle(root).getPropertyValue('--gcsa-z-modal').trim();
+  const parsedModal = Number.parseInt(modal, 10);
+  return Number.isFinite(parsedModal) ? parsedModal : FALLBACK_INITIAL;
+}
+
+export function provideGcsaZIndex(initial?: number): GcsaZIndexApi {
+  const api = createZIndexApi(initial ?? readInitialZIndex());
+  provide(GCSA_Z_INDEX_KEY, api);
+  return api;
+}
+
+export function useGcsaZIndex() {
+  const api = inject(GCSA_Z_INDEX_KEY, null);
+
+  function nextZIndex() {
+    return api?.next() ?? FALLBACK_INITIAL + Z_INDEX_STEP;
+  }
+
+  return { nextZIndex };
+}

package/src/composables/useMessage.ts

@@ -0,0 +1,9 @@
+import type { InjectionKey } from 'vue';
+
+export type GcsaMessageApi = {
+  success: (message: string) => void;
+  error: (message: string) => void;
+  info: (message: string) => void;
+};
+
+export const GCSA_MESSAGE_KEY: InjectionKey<GcsaMessageApi> = Symbol('gcsa-message');