@paraxe/vue 1.0.0

package/doc.md

@@ -0,0 +1,527 @@
+# Loba UI Vue
+
+Loba UI Vue is the Vue implementation of the Loba Design System. It provides reusable application UI so projects can focus on product logic, data, and behaviour instead of rebuilding common interface patterns.
+
+## Installation
+
+Import the components you need from `@paraxe/vue`.
+
+```ts
+import {
+  Button,
+  Card,
+  Stack,
+  Grid,
+  Table,
+  Sidebar,
+} from "@paraxe/vue";
+```
+
+Loba Design tokens and component styles must also be available to the project.
+
+## Core Principle
+
+Use Loba UI components for repeated UI responsibilities.
+
+```text
+Loba UI
+→ components
+→ behaviour
+→ states
+→ accessibility
+→ design consistency
+
+Application
+→ data
+→ business logic
+→ routing
+→ API calls
+→ page-specific composition
+```
+
+Do not recreate a Loba component with custom HTML/CSS when the existing component already owns that responsibility.
+
+## Layout
+
+### Stack
+
+Use `Stack` for vertical composition.
+
+```vue
+<Stack size="large" fullWidth>
+  <Heading level="h1">Prospects</Heading>
+  <Text>Manage your sales pipeline.</Text>
+</Stack>
+```
+
+`Stack` is intentionally composition-focused. Avoid adding unnecessary page-level wrappers just to reproduce its spacing.
+
+### Grid
+
+Use `Grid` for structured columns.
+
+```vue
+<Grid columns="3" size="medium">
+  <Card>...</Card>
+  <Card>...</Card>
+  <Card>...</Card>
+</Grid>
+```
+
+### Container
+
+Use `Container` for page content boundaries.
+
+```vue
+<Section>
+  <Container>
+    ...
+  </Container>
+</Section>
+```
+
+## Card and Surfaces
+
+`Card` is the standard bounded content container.
+
+```vue
+<Card>
+  ...
+</Card>
+```
+
+Card variants control containment and depth:
+
+```vue
+<Card variant="outlined">
+  ...
+</Card>
+
+<Card variant="elevated">
+  ...
+</Card>
+```
+
+Surface classes modify the visual layer independently:
+
+```vue
+<Card class="surface-raised">
+  ...
+</Card>
+```
+
+The important distinction is:
+
+```text
+Card
+→ container / border / radius / elevation / interaction
+
+surface-*
+→ background visual layer
+```
+
+Do not create a `<Surface>` wrapper around a Card.
+
+## Forms
+
+Loba UI provides:
+
+```text
+Input
+Textarea
+Select
+FormField
+Checkbox
+Radio
+Switch
+ChoiceGroup
+Choice
+```
+
+Use existing controls rather than recreating browser controls with application CSS.
+
+`ChoiceGroup` is intended for prominent visual choices:
+
+```vue
+<ChoiceGroup
+  v-model="projectType"
+  class="choice-group--grid-2"
+>
+  <Choice value="renovation">
+    Renovation
+  </Choice>
+
+  <Choice value="new-build">
+    New build
+  </Choice>
+</ChoiceGroup>
+```
+
+## Data
+
+Use the Data components for application records:
+
+```text
+List
+ListItem
+Table
+Pagination
+EmptyState
+```
+
+For example:
+
+```vue
+<Table
+  :columns="columns"
+  :rows="rows"
+  sortable
+  selectable
+  multiple
+/>
+```
+
+Let the component own its behaviour. Avoid wrapping a component in custom layout CSS when the component already provides that responsibility.
+
+For example, Pagination should normally be used directly:
+
+```vue
+<Pagination
+  :current-page="page"
+  :total-items="totalItems"
+  :page-size="pageSize"
+  @update:current-page="page = $event"
+/>
+```
+
+## Navigation
+
+### Sidebar
+
+Sidebar is the persistent application shell.
+
+```text
+Sidebar
+├── header
+├── navigation
+│   ├── SidebarGroup
+│   │   └── SidebarItem
+│   └── ...
+└── footer
+```
+
+Example:
+
+```vue
+<Sidebar :collapsed="collapsed">
+  <template #header>
+    ...
+  </template>
+
+  <SidebarGroup label="Workspace">
+    <SidebarItem active href="/dashboard">
+      Dashboard
+    </SidebarItem>
+
+    <SidebarItem>
+      Sales
+
+      <template #children>
+        <SidebarItem href="/calls">
+          Calls
+        </SidebarItem>
+
+        <SidebarItem href="/follow-ups">
+          Follow-ups
+        </SidebarItem>
+      </template>
+    </SidebarItem>
+  </SidebarGroup>
+
+  <template #footer>
+    ...
+  </template>
+</Sidebar>
+```
+
+Sidebar is router-agnostic. The application controls navigation and active state.
+
+### Tabs
+
+Tabs switch between views of the same context.
+
+```vue
+<Tabs v-model="activeTab">
+  <Tab value="overview">
+    Overview
+  </Tab>
+
+  <Tab value="activity">
+    Activity
+  </Tab>
+
+  <Tab value="documents">
+    Documents
+  </Tab>
+</Tabs>
+```
+
+The application owns the content:
+
+```vue
+<Card v-if="activeTab === 'overview'">
+  ...
+</Card>
+
+<Card v-else-if="activeTab === 'activity'">
+  ...
+</Card>
+```
+
+Loba UI does not provide a separate `TabPanel` component.
+
+### Breadcrumbs
+
+Breadcrumbs communicate hierarchical location.
+
+```vue
+<Breadcrumbs separator="›">
+  <Breadcrumb href="/dashboard">
+    Dashboard
+  </Breadcrumb>
+
+  <Breadcrumb href="/prospects">
+    Prospects
+  </Breadcrumb>
+
+  <Breadcrumb current>
+    James Wilson
+  </Breadcrumb>
+</Breadcrumbs>
+```
+
+## Overlays
+
+Loba UI provides four overlay patterns:
+
+```text
+Dialog
+→ focused task or decision
+
+Drawer
+→ larger contextual workspace
+
+Popover
+→ contextual interactive content
+
+Tooltip
+→ short non-interactive explanation
+```
+
+### Dialog
+
+Use for focused tasks:
+
+```vue
+<Dialog v-model="showDialog">
+  <Stack size="large">
+    ...
+  </Stack>
+</Dialog>
+```
+
+### Drawer
+
+Use for larger contextual workspaces:
+
+```vue
+<Drawer v-model="showDrawer">
+  <Stack size="large">
+    ...
+  </Stack>
+</Drawer>
+```
+
+### Popover
+
+Use for interactive contextual UI:
+
+```vue
+<Popover>
+  <template #trigger>
+    <Button variant="secondary">
+      Filters
+    </Button>
+  </template>
+
+  ...
+</Popover>
+```
+
+### Tooltip
+
+Use for short explanations:
+
+```vue
+<Tooltip text="Delete prospect">
+  <Button variant="ghost">
+    Delete
+  </Button>
+</Tooltip>
+```
+
+## Feedback
+
+Loba UI provides:
+
+```text
+Alert
+→ persistent in-flow message
+
+Progress
+→ operation completion
+
+Skeleton
+→ loading placeholder
+
+Toast
+→ temporary floating notification
+```
+
+These should not overlap in purpose.
+
+## Composition Rules
+
+Prefer:
+
+```vue
+<Card class="surface-raised">
+  <Stack size="large" fullWidth>
+    <Heading level="h2">
+      Pipeline
+    </Heading>
+
+    <Table ... />
+  </Stack>
+</Card>
+```
+
+over creating custom page-specific UI components for every repeated visual pattern.
+
+Create a new component only when a pattern has a **real reusable responsibility**.
+
+Avoid:
+
+```text
+ProspectCard
+DashboardPanel
+ToolbarWrapper
+TableContainer
+SectionBox
+```
+
+unless repeated application work proves that they deserve to exist.
+
+## Custom CSS
+
+Custom CSS is allowed.
+
+Loba UI is not intended to prevent application-specific styling. It is intended to remove unnecessary repetition.
+
+Use custom CSS for:
+
+```text
+page-specific layout
+brand-specific compositions
+unique visual treatments
+application-specific responsive behaviour
+```
+
+Do not use custom CSS to recreate:
+
+```text
+buttons
+cards
+forms
+tables
+navigation
+dialogs
+drawers
+feedback
+```
+
+when Loba UI already provides them.
+
+## Design Tokens
+
+Loba Design separates:
+
+```text
+tokens.css
+→ structural values
+
+themes/*.css
+→ colours / semantic theme values
+
+components.css
+→ component implementation styles
+```
+
+Components should consume existing tokens instead of inventing duplicate values.
+
+For example:
+
+```css
+background: var(--surface-raised);
+border-color: var(--border-default);
+color: var(--text-primary);
+```
+
+## Framework Responsibility
+
+Loba UI Vue provides Vue-specific implementations.
+
+The design language remains in Loba Design so the same system can eventually support other frameworks.
+
+The Vue layer should therefore focus on:
+
+```text
+props
+events
+slots
+state
+Vue behaviour
+```
+
+while shared visual decisions remain in Loba Design.
+
+## Building an Application
+
+A typical Loba application can be structured around:
+
+```text
+App Shell
+├── Sidebar
+│
+└── Main
+    ├── Breadcrumbs
+    ├── SectionHeader
+    ├── Cards
+    ├── Forms
+    ├── Data
+    ├── Tabs
+    ├── Dialog / Drawer
+    └── Feedback
+```
+
+The intended workflow is:
+
+```text
+Choose the Loba component
+→ compose it
+→ connect application state
+→ add business logic
+→ add custom CSS only when genuinely necessary
+```
+
+Loba UI exists to make application building faster without replacing the developer's understanding of HTML, CSS, JavaScript, Vue, or TypeScript.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@paraxe/vue",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@paraxe/core": "workspace:*",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.1",
+    "vite": "^7.1.2",
+    "vue-tsc": "^3.0.5",
+    "typescript": "^5.9.2"
+  }
+}

package/src/composites/Accordion.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { provide, ref, computed } from "vue";
+
+type AccordionContext = {
+  openItems: Readonly<ReturnType<typeof ref<string[]>>>;
+  isOpen: (id: string) => boolean;
+  toggleItem: (id: string) => void;
+};
+
+const props = withDefaults(
+  defineProps<{
+    multiple?: boolean;
+    collapsible?: boolean;
+    defaultOpen?: string[];
+  }>(),
+  {
+    multiple: false,
+    collapsible: true,
+    defaultOpen: () => [],
+  },
+);
+
+const openItems = ref<string[]>([...props.defaultOpen]);
+
+function isOpen(id: string) {
+  return openItems.value.includes(id);
+}
+
+function toggleItem(id: string) {
+  const currentlyOpen = isOpen(id);
+
+  if (currentlyOpen) {
+    if (!props.collapsible) {
+      return;
+    }
+
+    openItems.value = openItems.value.filter((item) => item !== id);
+    return;
+  }
+
+  if (props.multiple) {
+    openItems.value = [...openItems.value, id];
+    return;
+  }
+
+  openItems.value = [id];
+}
+
+provide("loba-accordion", {
+  openItems,
+  isOpen,
+  toggleItem,
+} satisfies AccordionContext);
+</script>
+
+<template>
+  <div class="accordion">
+    <slot />
+  </div>
+</template>

package/src/composites/AccordionItem.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import { computed, inject } from "vue";
+
+interface Props {
+  id: string;
+  disabled?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  disabled: false,
+});
+
+type AccordionContext = {
+  isOpen: (id: string) => boolean;
+  toggleItem: (id: string) => void;
+};
+const injectedAccordion = inject<AccordionContext>("loba-accordion");
+
+if (!injectedAccordion) {
+  throw new Error(
+    "AccordionItem must be used inside an Accordion.",
+  );
+}
+
+const accordion = injectedAccordion;
+
+if (!accordion) {
+  throw new Error(
+    "AccordionItem must be used inside an Accordion.",
+  );
+}
+
+const isOpen = computed(() => accordion.isOpen(props.id));
+
+function toggle() {
+  if (!props.disabled) {
+    accordion.toggleItem(props.id);
+  }
+}
+</script>
+
+<template>
+  <div
+    class="accordion-item"
+    :class="{ 'accordion-item--open': isOpen }"
+  >
+    <button
+      type="button"
+      class="accordion-trigger"
+      :disabled="props.disabled"
+      :aria-expanded="isOpen"
+      :aria-controls="`accordion-${props.id}`"
+      @click="toggle"
+    >
+      <slot name="trigger" />
+    </button>
+
+    <div
+      v-show="isOpen"
+      :id="`accordion-${props.id}`"
+      class="accordion-content"
+    >
+      <slot />
+    </div>
+  </div>
+</template>

package/src/composites/ButtonGroup.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { computed } from "vue";
+
+type ButtonGroupAlign = "start" | "center" | "end";
+
+interface Props {
+  align?: ButtonGroupAlign;
+  stack?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  align: "start",
+  stack: false,
+});
+
+const buttonGroupClasses = computed(() => ({
+  "button-group--center": props.align === "center",
+  "button-group--end": props.align === "end",
+  "button-group--stack": props.stack,
+}));
+</script>
+
+<template>
+  <div class="button-group" :class="buttonGroupClasses">
+    <slot />
+  </div>
+</template>

package/src/composites/SectionHeader.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+interface Props {
+  width?: "default" | "wide";
+  align?: "left" | "center";
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  width: "default",
+  align: "left",
+});
+</script>
+
+<template>
+  <header
+    class="section-header"
+    :class="{
+      'section-header--wide': props.width === 'wide',
+      'section-header--center': props.align === 'center',
+    }"
+  >
+    <slot />
+  </header>
+</template>