mgv-backoffice 1.20.0 → 1.22.0

package/README.md

@@ -414,29 +414,43 @@ import { ColoredSquares, ColorsEnums } from 'mgv-backoffice'
 
 ### EarningsCard
 
-Earnings summary card with formatted currency display.
+Earnings summary card with formatted currency display. Supports a signed P&L
+mode that renders a red loss theme (and a downward trend glyph) for negative
+amounts.
 
 **Props:**
 
 | Prop       | Type     | Default                 | Description          |
 | ---------- | -------- |-------------------------|----------------------|
 | `title`    | `String` | `'TOTAL EARNINGS'`      | Card heading         |
-| `amount`   | `Number` | `0`                     | Monetary value       |
+| `amount`   | `Number` | `0`                     | Monetary value (a stringified number is coerced) |
 | `subtitle` | `String` | `'Lifetime commission'` | Subheading text      |
 | `badge`    | `String` | `''`                    | Optional badge label |
 | `currency` | `String` | `'$'`                   | Currency symbol      |
 | `decimals` | `Number` | `2`                     | Fraction digits shown for the amount |
+| `accent`   | `'orange' \| 'emerald' \| 'red'` | `'orange'` | Card theme. `emerald` tints it green; `red` is the loss theme. |
+| `signed`   | `Boolean` | `false`                | Treat `amount` as a signed P&L figure: a negative value automatically switches to the `red` loss theme and flips the trend glyph to point **down**; a non-negative value keeps the chosen `accent` and the upward glyph. |
 
 **Example:**
 
 ```vue
 <template>
+  <!-- Always-positive total: original behaviour. -->
   <EarningsCard
     title="Monthly Revenue"
     :amount="12500"
     subtitle="April 2026"
     currency="€"
   />
+
+  <!-- Signed P&L: renders red + a down arrow when the amount is negative. -->
+  <EarningsCard
+    title="TOTAL P&L"
+    :amount="-128.4"
+    subtitle="Realised + unrealised"
+    accent="emerald"
+    signed
+  />
 </template>
 
 <script setup lang="ts">
@@ -1150,6 +1164,135 @@ import { BaseCopyButton, BaseToastEnum } from 'mgv-backoffice'
 
 ---
 
+## Forms & tables
+
+These components use `dark:` Tailwind variants, so the consuming app must map
+the `dark` variant to the `.dark` class that `useTheme()` toggles (see
+[Tailwind setup for consumers](#tailwind-setup-for-consumers)).
+
+### BaseInput
+
+Themed text/number input carrying the shared field skin (slate border,
+`bg-slate-50` / dark `bg-slate-900` surface). Everything else — `placeholder`,
+`id`, `disabled`, `step`/`min`, extra classes like `font-mono` or
+`placeholder:*` — falls through via attrs and Vue class merging.
+
+**Props:**
+
+| Prop         | Type               | Default  | Description |
+| ------------ | ------------------ | -------- | ----------- |
+| `modelValue` | `String \| Number` | `''`     | `v-model` value. |
+| `type`       | `String`           | `'text'` | Native input type. |
+| `size`       | `String`           | `'md'`   | `'md'` = `px-3 py-2`, `'sm'` = `px-2 py-1.5`. |
+| `block`      | `Boolean`          | `true`   | Full-width (`w-full`); set `false` for inline fields. |
+
+**Emits:** `update:modelValue(value: string)` — always the raw string; parse
+numbers in the owner.
+
+```vue
+<BaseInput v-model="query" placeholder="e.g. AMD or BTC" class="font-mono" />
+```
+
+### BaseSelect
+
+Themed `<select>` sharing BaseInput's field skin. Options come from the
+default slot so callers keep full control of `<option>` rendering.
+
+**Props:**
+
+| Prop         | Type               | Default | Description |
+| ------------ | ------------------ | ------- | ----------- |
+| `modelValue` | `String \| Number` | `''`    | `v-model` value. |
+| `size`       | `String`           | `'sm'`  | `'sm'` = `px-2 py-1.5`, `'md'` = `px-3 py-2`. |
+| `block`      | `Boolean`          | `true`  | Full-width; set `false` for inline selects. |
+
+**Slots:** `default` — the `<option>` elements.
+**Emits:** `update:modelValue(value: string)`.
+
+```vue
+<BaseSelect v-model="strategyType">
+  <option v-for="e in catalog" :key="e.type" :value="e.type" :title="e.description">
+    {{ e.label }}
+  </option>
+</BaseSelect>
+```
+
+### BaseSegmentedControl
+
+Segmented button group ("All | Stock | Crypto"). One button per option; the
+selected one gets the filled treatment and `aria-pressed="true"`.
+
+**Props:**
+
+| Prop          | Type                | Default  | Description |
+| ------------- | ------------------- | -------- | ----------- |
+| `options`     | `SegmentedOption[]` | **required** | `{ value, label, title? }` per button. |
+| `modelValue`  | `String \| Number`  | **required** | Selected option's `value` (`v-model`). |
+| `variant`     | `String`            | `'base'` | `'base'` (`px-3 py-2`, emerald-500 fill), `'wide'` (`px-4 py-2`, emerald-600 fill), `'toolbar'` (`h-9` uppercase `text-xs` with focus-visible rings). |
+| `ariaLabel`   | `String`            | `''`     | When set, the wrapper renders `role="group"` + `aria-label`. |
+| `optionClass` | `Function`          | —        | `(option, active) => string` override for per-button fill classes (e.g. severity colours); layout stays owned by the variant. |
+
+**Emits:** `update:modelValue(value)`.
+
+```vue
+<BaseSegmentedControl v-model="assetFilter" :options="ASSET_FILTERS" />
+<BaseSegmentedControl v-model="exchange" :options="EXCHANGES" variant="wide" aria-label="Exchange" />
+```
+
+### BaseTable
+
+Styling shell for data tables — **not** a data grid. Owns the table skin
+(slate header band, `px-4 py-3` header cells, empty-state row); body rows are
+the caller's own `<tr>` markup via the default slot. Wrap it yourself for
+scrolling/card chrome (e.g. a `BaseRow` with `overflow-x-auto`).
+
+**Props:**
+
+| Prop        | Type            | Default      | Description |
+| ----------- | --------------- | ------------ | ----------- |
+| `columns`   | `TableColumn[]` | **required** | `{ label, align? }`; `align: 'right'` right-aligns the header cell. |
+| `empty`     | `Boolean`       | `false`      | True renders the empty-state row spanning every column. |
+| `emptyText` | `String`        | `'No rows.'` | Fallback empty-state text. |
+
+**Slots:** `default` — the `<tr>` rows; `empty` — custom empty-state content.
+
+```vue
+<BaseTable :columns="COLUMNS" :empty="rows.length === 0">
+  <template #empty>No trades match your filters.</template>
+  <tr v-for="row in rows" :key="row.id" class="border-t border-slate-200 dark:border-slate-700">
+    …
+  </tr>
+</BaseTable>
+```
+
+### BaseSpecFields
+
+Spec-driven form fields: renders a select / checkbox / number input per
+`SpecField`, with labels and help text, in a responsive two-column grid. Feed
+it a backend-described catalogue and every form editing those values stays in
+lockstep. Never mutates `params` — every edit is emitted as `(key, value)`
+and the owner writes it back into its own state.
+
+**Props:**
+
+| Prop     | Type                             | Default      | Description |
+| -------- | -------------------------------- | ------------ | ----------- |
+| `specs`  | `SpecField[]`                    | **required** | `{ key, label, type: 'decimal' \| 'integer' \| 'boolean' \| 'select', options?, step?, min?, help? }`. |
+| `params` | `Record<string, SpecFieldValue>` | **required** | Current values keyed by `spec.key`. |
+
+**Slots:** `after` (`{ spec }`) — extra content under each field (e.g. a live
+preview attached to one key).
+**Emits:** `update(key: string, value: SpecFieldValue)` — numbers are parsed
+(`parseFloat`); unparseable input passes through raw so the owner's
+validation can catch it.
+
+```vue
+<BaseSpecFields :specs="entry.params" :params="form.params"
+  @update="(key, value) => (form.params[key] = value)" />
+```
+
+---
+
 ## Composables
 
 ```ts

package/dist/components/BaseInput.vue.d.ts

@@ -0,0 +1,21 @@
+interface Props {
+    modelValue?: string | number | null;
+    /** Native input type ('text', 'number', 'password', …). */
+    type?: string;
+    /** 'md' = px-3 py-2 (default); 'sm' = px-2 py-1.5 compact. */
+    size?: 'sm' | 'md';
+    /** Full-width (w-full). Set false for inline fields. */
+    block?: boolean;
+}
+declare const __VLS_export: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: string) => any;
+}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+}>, {
+    type: string;
+    size: "sm" | "md";
+    block: boolean;
+    modelValue: string | number | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/BaseSegmentedControl.vue.d.ts

@@ -0,0 +1,25 @@
+import { SegmentedOption } from '../types/segmented';
+interface Props {
+    options: readonly SegmentedOption[];
+    modelValue: string | number;
+    variant?: 'base' | 'wide' | 'toolbar';
+    /** When set, the wrapper announces itself as a labelled group. */
+    ariaLabel?: string;
+    /**
+     * Override the fill (colour) classes per button — receives the option and
+     * whether it is the selected one. Defaults to the variant's emerald/slate
+     * treatment.
+     */
+    optionClass?: (option: SegmentedOption, active: boolean) => string;
+}
+declare const __VLS_export: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: any) => any;
+}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: any) => any) | undefined;
+}>, {
+    variant: "base" | "wide" | "toolbar";
+    ariaLabel: string;
+    optionClass: (option: SegmentedOption, active: boolean) => string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/BaseSelect.vue.d.ts

@@ -0,0 +1,28 @@
+interface Props {
+    modelValue?: string | null;
+    /** 'sm' = px-2 py-1.5 (default, the usual select height); 'md' = px-3 py-2. */
+    size?: 'sm' | 'md';
+    /** Full-width (w-full). Set false for inline selects. */
+    block?: boolean;
+}
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:modelValue": (value: any) => any;
+}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: any) => any) | undefined;
+}>, {
+    size: "sm" | "md";
+    block: boolean;
+    modelValue: string | null;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/BaseSpecFields.vue.d.ts

@@ -0,0 +1,23 @@
+import { SpecField, SpecFieldValue } from '../types/specField';
+type __VLS_Props = {
+    specs: SpecField[];
+    params: Record<string, SpecFieldValue>;
+};
+type __VLS_Slots = {
+    after?: (props: {
+        spec: SpecField;
+    }) => unknown;
+};
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    update: (key: string, value: SpecFieldValue) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onUpdate?: ((key: string, value: SpecFieldValue) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/BaseTable.vue.d.ts

@@ -0,0 +1,26 @@
+import { TableColumn } from '../types/table';
+interface Props {
+    columns: TableColumn[];
+    /** True when there are no rows — renders the empty-state row. */
+    empty?: boolean;
+    /** Fallback empty-state text; the `empty` slot overrides it. */
+    emptyText?: string;
+}
+declare var __VLS_1: {}, __VLS_3: {};
+type __VLS_Slots = {} & {
+    empty?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_base: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{}>, {
+    emptyText: string;
+    empty: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/EarningsCard.vue.d.ts

@@ -1,12 +1,13 @@
 /**
  * Accent colour of the card. Defaults to `orange` so existing consumers are
- * unaffected; `emerald` lets a host app tint the card to a green-themed brand.
- * Each accent carries the full literal Tailwind class strings (rather than a
- * single interpolated hue) so the classes are statically detectable and the
- * two themes can differ in more than hue — e.g. orange renders the amount in
- * neutral grey while emerald renders it in the accent itself.
+ * unaffected; `emerald` lets a host app tint the card to a green-themed brand,
+ * and `red` renders a loss/negative theme (also selected automatically by
+ * `signed`, see below). Each accent carries the full literal Tailwind class
+ * strings (rather than a single interpolated hue) so the classes are statically
+ * detectable and the themes can differ in more than hue — e.g. orange renders
+ * the amount in neutral grey while emerald/red render it in the accent itself.
  */
-type Accent = 'orange' | 'emerald';
+type Accent = 'orange' | 'emerald' | 'red';
 interface Props {
     title?: string;
     amount?: number;
@@ -15,6 +16,15 @@ interface Props {
     currency?: string;
     decimals?: number;
     accent?: Accent;
+    /**
+     * Treat the card as a signed P&L figure. When `true` and the amount is
+     * negative, the card renders the loss theme automatically: the `red` accent
+     * (border / amount / subtitle / icon-box recoloured) AND the trend glyph
+     * flipped to point DOWN. A non-negative amount keeps the chosen `accent` and
+     * the upward glyph. Defaults to `false` so existing consumers — which use the
+     * card for always-positive totals like lifetime earnings — are unaffected.
+     */
+    signed?: boolean;
 }
 declare const __VLS_export: import('vue').DefineComponent<Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<Props> & Readonly<{}>, {
     title: string;
@@ -24,6 +34,7 @@ declare const __VLS_export: import('vue').DefineComponent<Props, {}, {}, {}, {},
     currency: string;
     decimals: number;
     accent: Accent;
+    signed: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/index.d.ts

@@ -28,6 +28,11 @@ export { default as BaseCopyButton } from './components/BaseCopyButton.vue';
 export { default as BaseGoogleSignInButton } from './components/BaseGoogleSignInButton.vue';
 export { default as BaseLoginForm } from './components/BaseLoginForm.vue';
 export { default as BaseNotificationPanel } from './components/BaseNotificationPanel.vue';
+export { default as BaseInput } from './components/BaseInput.vue';
+export { default as BaseSelect } from './components/BaseSelect.vue';
+export { default as BaseSegmentedControl } from './components/BaseSegmentedControl.vue';
+export { default as BaseTable } from './components/BaseTable.vue';
+export { default as BaseSpecFields } from './components/BaseSpecFields.vue';
 export { useTheme, initTheme } from './composables/useTheme';
 export type { UseThemeOptions } from './composables/useTheme';
 export { useThemeClasses } from './composables/useThemeClasses';
@@ -54,6 +59,9 @@ export type { NavItem, NavSection } from './types/sidebar';
 export type { EntityPickerItem } from './types/entityPicker';
 export type { LoginCredentials } from './types/auth';
 export type { NotificationItem } from './types/notification';
+export type { SegmentedOption } from './types/segmented';
+export type { TableColumn } from './types/table';
+export type { SpecField, SpecFieldType, SpecFieldValue } from './types/specField';
 export { getBaseColor, getBaseColorOf } from './utils/util';
 export { methodBadgeSolid, methodBadgeBright, statusBadgeSolid, statusBadgeTinted, } from './utils/httpColors';
 export { sanitizeHtml, isSafeHref } from './utils/sanitizeHtml';

package/dist/types/segmented.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One choice in a BaseSegmentedControl. `value` is what the control emits,
+ * `label` what the button shows; `title` becomes the button's tooltip.
+ * Generic so callers with union-typed values ('all' | 'STOCK' | …) keep
+ * full type-safety through v-model.
+ */
+export interface SegmentedOption<T extends string | number = string | number> {
+    value: T;
+    label: string;
+    title?: string;
+}

package/dist/types/specField.d.ts

@@ -0,0 +1,23 @@
+/** Which input a BaseSpecFields entry renders. */
+export type SpecFieldType = 'decimal' | 'integer' | 'boolean' | 'select';
+/**
+ * One field of a spec-driven form: the field's key in the value map, its
+ * label, which input to render, and optional validation/rendering hints.
+ * Members are loose (`| null` allowed) so backend-described catalogues can be
+ * passed straight through without mapping.
+ */
+export interface SpecField {
+    key: string;
+    label: string;
+    type: SpecFieldType;
+    /** Choices for `type: 'select'`. */
+    options?: string[] | null;
+    /** Step for numeric inputs; defaults to 1 (integer) / 0.01 (decimal). */
+    step?: number | null;
+    /** Minimum for numeric inputs. */
+    min?: number | null;
+    /** Help text rendered under the field. */
+    help?: string | null;
+}
+/** A field's current value in the owner's form state. */
+export type SpecFieldValue = number | boolean | string;

package/dist/types/table.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One header cell of a BaseTable. `align: 'right'` right-aligns the header
+ * (numeric columns); body cells are the caller's markup and align themselves.
+ */
+export interface TableColumn {
+    label: string;
+    align?: 'left' | 'right';
+}