@flux-ui/types 3.0.0-next.7 → 3.0.0-next.70

package/README.md

@@ -1,45 +1,39 @@
-# Flux
+# `@flux-ui/types`
 
-This repository contains the source code for the basic components that are used throughout our front-end projects. It
-targets Vue 3+. Please read the following instructions and checks in order to proceed.
+Public TypeScript types shared across the Flux UI packages.
 
-## 📦 Registry
+This package has **no build step** — it ships its TypeScript sources directly.
 
-- The UI library package is available under `@flux-ui/components`.
-- The Dashboard library package is available under `@flux-ui/dashboard`.
-- The internal package is available under `@flux-ui/internals`.
+## Highlights
 
-## ⚠️ Requirements
+| File            | Contents                                                                |
+|-----------------|-------------------------------------------------------------------------|
+| `common.ts`     | Cross-cutting types — `FluxColor`, `FluxSize`, `FluxIconName`, `FluxTo` |
+| `components.ts` | Per-component `Props`, `Emits`, and `Slots` types                       |
+| `form.ts`       | Form-related types                                                      |
+| `filter.ts`     | Filter component types                                                  |
+| `notify.ts`     | Snackbar, alert, confirm, and prompt types                              |
+| `statistics.ts` | Types for `@flux-ui/statistics`                                         |
 
-- Install Node.js ^22
-- Install pnpm using `npm i -g pnpm`.
-- Configure a new environment variable `FONTAWESOME_NPM_AUTH_TOKEN`. This should be a valid Font Awesome private npm auth token.
-- Use `pnpm install` to install the required packages.
-- Use `pnpm dev` to start a build watcher for both targets.
-- Use `pnpm build` to build a production bundle.
-- Use `pnpm link` to link the dist folder of flux to your global node_modules.
+> Component-owned types live next to their component as inline `defineProps` / `defineEmits` / `defineSlots`.
+> Only types with cross-package or cross-component reuse belong here.
 
-## 🪵 Git
+## ⭐️ Prerequisites
 
-All commit messages and branches will be in English.
+- Bun >= 1.2.13
+- Node >= 23
 
-### Branches
+## 🚀 Getting started
 
-- **Main** — Contains the latest stable release and is the exact source that is running in production.
-- **Develop** — Contains the latest staging release that is marked for deployment and is the exact source that is running on staging.
-- **Feature branches** — Any feature should have its own feature branch. Once complete, the branch should be merged into the _develop_ branch and the feature branch should be deleted.
-- **Bugfix branches** — When a bug is found, it should be fixed within a bugfix branch. Once complete the branch should be merged into the _develop_ branch and the feature branch should be deleted.
+1. Make sure the Flux monorepo is checked out.
+2. Run `bun install` in the project root.
 
-### Commit messages
+There is no build step; consumers import directly from `./src/index.ts`.
 
-Commit messages are bound to the following templates:
+## 📦 Sibling packages
 
-- `<type>: <message> `
-- `<type>(<feature>): <message>`
-- `<type>(<feature>): <message> [<issue-number>]`
-
-#### Examples
-
-- `feat(expandable): adds header slot to expandable.`
-- `feat(expandable): adds header slot to expandable. [FLUX-123]`
-- `chore: adds vue 3 build target.`
+- [`@flux-ui/components`](../components)
+- [`@flux-ui/internals`](../internals)
+- [`@flux-ui/statistics`](../statistics)
+- [`@flux-ui/dashboard`](../dashboard)
+- [`@flux-ui/application`](../application)

package/package.json

@@ -1,29 +1,20 @@
 {
     "name": "@flux-ui/types",
     "description": "Contains all public types of Flux UI packages.",
-    "version": "3.0.0-next.7",
+    "version": "3.0.0-next.70",
     "type": "module",
     "license": "MIT",
     "funding": "https://github.com/sponsors/basmilius",
-    "homepage": "https://flux.bas.dev",
+    "homepage": "https://flux-ui.dev",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/basmilius/flux.git",
-        "directory": "packages/primitives"
+        "directory": "packages/types"
     },
     "keywords": [
-        "ui library",
-        "component library",
-        "design system",
-        "vue",
-        "vue 3",
-        "ui",
-        "components",
-        "flux"
+        "flux",
+        "types"
     ],
-    "scripts": {
-        "prepublishOnly": "cp ../../README.md ."
-    },
     "exports": {
         ".": "./src/index.ts"
     },
@@ -32,16 +23,20 @@
         "provenance": true
     },
     "files": [
-        "src",
-        "tsconfig.json"
+        "src"
     ],
     "main": "./src/index.ts",
     "module": "./src/index.ts",
     "types": "./src/index.ts",
     "typings": "./src/index.ts",
     "sideEffects": false,
-    "dependencies": {},
+    "peerDependencies": {
+        "@fortawesome/fontawesome-common-types": "^7.2.0",
+        "luxon": "^3.7.2"
+    },
     "devDependencies": {
-        "@types/luxon": "^3.6.2"
+        "@fortawesome/fontawesome-common-types": "^7.2.0",
+        "@types/luxon": "^3.7.1",
+        "luxon": "^3.7.2"
     }
 }

package/src/common.ts

@@ -1,9 +1,16 @@
-import type { FontAwesome } from './font-awesome';
-import type { MaterialSymbol } from './material-symbols';
+import type { IconName as FontAwesome } from '@fortawesome/fontawesome-common-types';
 
-export type FluxIconName = FontAwesome | MaterialSymbol;
-export type FluxFontAwesomeIconName = FontAwesome;
-export type FluxMaterialIconName = MaterialSymbol;
+export type FluxIconName = FontAwesome;
+
+export type FluxAlignment =
+    | 'start'
+    | 'center'
+    | 'end';
+
+export type FluxAlign =
+    | FluxAlignment
+    | 'stretch'
+    | 'baseline';
 
 export type FluxColor =
     | 'gray'
@@ -17,6 +24,17 @@ export type FluxDirection =
     | 'horizontal'
     | 'vertical';
 
+export type FluxFlexWrap =
+    | 'wrap'
+    | 'nowrap'
+    | 'wrap-reverse';
+
+export type FluxJustify =
+    | FluxAlignment
+    | 'between'
+    | 'around'
+    | 'evenly';
+
 export type FluxInputMask =
     | 'bic'
     | 'iban'

package/src/components.ts

@@ -53,3 +53,47 @@ export type FluxSegmentedControlItemObject = {
     readonly icon?: FluxIconName;
     readonly label?: string;
 };
+
+export type FluxKanbanMoveEvent = {
+    readonly itemId: string | number;
+    readonly fromColumnId: string | number;
+    readonly toColumnId: string | number;
+    readonly beforeItemId?: string | number;
+};
+
+export type FluxKanbanMoveColumnEvent = {
+    readonly columnId: string | number;
+    readonly beforeColumnId?: string | number;
+};
+
+export type FluxTreeViewOption = {
+    readonly id: string | number;
+    readonly label: string;
+    readonly icon?: FluxIconName;
+    readonly children?: FluxTreeViewOption[];
+};
+
+export type FluxCommandSubAction = {
+    readonly label: string;
+    readonly icon?: FluxIconName;
+    readonly onActivate: () => void;
+};
+
+export type FluxCommandSourceItem = {
+    readonly id: string | number;
+    readonly label: string;
+    readonly subLabel?: string;
+    readonly icon?: FluxIconName;
+    readonly command?: string;
+    readonly subActions?: FluxCommandSubAction[];
+    readonly onActivate: () => void;
+};
+
+export type FluxCommandSource = {
+    readonly key: string;
+    readonly label: string;
+    readonly icon?: FluxIconName;
+    readonly tab?: boolean;
+    readonly items: FluxCommandSourceItem[];
+    readonly fetchSearch?: (query: string) => Promise<FluxCommandSourceItem[]>;
+};

package/src/filter.ts

@@ -1,12 +1,37 @@
 import type { DateTime } from 'luxon';
 import type { FluxIconName } from './common';
 
+export type FluxFilterValueSingle =
+    | DateTime
+    | string
+    | boolean
+    | number
+    | null;
+
+export type FluxFilterValue =
+    | FluxFilterValueSingle
+    | FluxFilterValueSingle[];
+
+export type FluxFilterState<T extends Record<string, unknown> = Record<string, FluxFilterValue>> = T;
+
+export type FluxFilterDefinition<TValue = FluxFilterValue> = {
+    readonly type: string;
+    readonly name: string;
+    readonly label: string;
+    readonly icon?: FluxIconName;
+    readonly disabled?: boolean;
+    readonly defaultValue?: TValue;
+    getValueLabel(value: TValue): Promise<string | null>;
+    onChange?(value: TValue): void;
+    onClear?(): void;
+};
+
 export type FluxFilterBase = {
     getValueLabel(value: FluxFilterValue): Promise<string | null>;
-
     readonly icon?: FluxIconName;
     readonly label: string;
     readonly name: string;
+    readonly disabled?: boolean;
 };
 
 export type FluxFilterItem =
@@ -41,6 +66,7 @@ export type FluxFilterOptionHeader = {
 };
 
 export type FluxFilterOptionItem = {
+    readonly icon?: FluxIconName;
     readonly label: string;
     readonly value: FluxFilterValueSingle;
 };
@@ -49,21 +75,36 @@ export type FluxFilterOptionRow =
     | FluxFilterOptionHeader
     | FluxFilterOptionItem;
 
-export type FluxFilterValueSingle =
-    | DateTime
-    | string
-    | boolean
-    | number
-    | null;
+export type FluxFilterSpec = {
+    readonly icon?: FluxIconName;
+    readonly label: string;
+    readonly name: string;
+    readonly disabled?: boolean;
+    readonly defaultValue?: FluxFilterValue;
+    onChange?(value: FluxFilterValue): void;
+    onClear?(): void;
+};
 
-export type FluxFilterValue =
-    | FluxFilterValueSingle
-    | FluxFilterValueSingle[];
+export type FluxFilterDateSpec = FluxFilterSpec;
+
+export type FluxFilterDateRangeSpec = FluxFilterSpec;
+
+export type FluxFilterOptionSpec = FluxFilterSpec & {
+    readonly options: FluxFilterOptionRow[];
+};
 
-export type FluxFilterState = {
-    get resettable(): string[];
+export type FluxFilterOptionAsyncSpec = FluxFilterSpec & {
+    fetchOptions(ids: FluxFilterValue[]): Promise<FluxFilterOptionRow[]>;
+};
+
+export type FluxFilterOptionsSpec = FluxFilterSpec & {
+    readonly options: FluxFilterOptionRow[];
+};
+
+export type FluxFilterOptionsAsyncSpec = FluxFilterSpec & {
+    fetchOptions(ids: FluxFilterValue[]): Promise<FluxFilterOptionRow[]>;
+};
 
-    reset(): void;
-} & {
-    [key: string]: FluxFilterValue | Function;
+export type FluxFilterRangeSpec = FluxFilterSpec & {
+    formatter?(value: number): string;
 };

package/src/form.ts

@@ -1,8 +1,32 @@
 import type { FluxIconName } from './common';
 
+export type FluxFormInputBaseProps = {
+    readonly autoFocus?: boolean;
+    readonly disabled?: boolean;
+    readonly error?: string | null;
+    readonly isCondensed?: boolean;
+    readonly isLoading?: boolean;
+    readonly isReadonly?: boolean;
+    readonly isSecondary?: boolean;
+    readonly name?: string;
+    readonly placeholder?: string;
+};
+
+export type FluxFormTreeViewSelectOption = {
+    readonly id: string | number;
+    readonly label: string;
+    readonly icon?: FluxIconName;
+    readonly selectable?: boolean;
+    readonly children?: FluxFormTreeViewSelectOption[];
+};
+
+export type FluxFormTreeViewSelectValue = FluxFormTreeViewSelectValueSingle | FluxFormTreeViewSelectValueSingle[];
+export type FluxFormTreeViewSelectValueSingle = string | number;
+
 export type FluxFormSelectGroup = {
     readonly icon?: FluxIconName;
     readonly label: string;
+    readonly value?: never;
 };
 
 export type FluxFormSelectOption = {
@@ -10,6 +34,8 @@ export type FluxFormSelectOption = {
     readonly command?: string;
     readonly commandIcon?: FluxIconName;
     readonly icon?: FluxIconName;
+    readonly imageAlt?: string;
+    readonly imageSrc?: string;
     readonly label: string;
     readonly selectable?: boolean;
     readonly value: string | number | null;

package/src/index.ts

@@ -1,12 +1,14 @@
 export type {
+    FluxAlign,
+    FluxAlignment,
     FluxAutoCompleteType,
     FluxColor,
     FluxDirection,
-    FluxFontAwesomeIconName,
+    FluxFlexWrap,
     FluxIconName,
     FluxInputMask,
     FluxInputType,
-    FluxMaterialIconName,
+    FluxJustify,
     FluxMaybePromise,
     FluxPressableType,
     FluxSize,
@@ -18,35 +20,54 @@ export type {
     FluxButtonProps,
     FluxButtonSize,
     FluxButtonSlots,
+    FluxCommandSource,
+    FluxCommandSourceItem,
+    FluxCommandSubAction,
     FluxFocalPointObject,
+    FluxKanbanMoveColumnEvent,
+    FluxKanbanMoveEvent,
     FluxLegendObject,
     FluxPercentageBarItemObject,
-    FluxSegmentedControlItemObject
+    FluxSegmentedControlItemObject,
+    FluxTreeViewOption
 } from './components';
 
 export type {
     FluxFilterBase,
     FluxFilterDateEntry,
     FluxFilterDateRangeEntry,
+    FluxFilterDateRangeSpec,
+    FluxFilterDateSpec,
+    FluxFilterDefinition,
     FluxFilterItem,
+    FluxFilterOptionAsyncSpec,
     FluxFilterOptionEntry,
     FluxFilterOptionHeader,
     FluxFilterOptionItem,
     FluxFilterOptionRow,
+    FluxFilterOptionSpec,
+    FluxFilterOptionsAsyncSpec,
     FluxFilterOptionsEntry,
+    FluxFilterOptionsSpec,
     FluxFilterRangeEntry,
+    FluxFilterRangeSpec,
+    FluxFilterSpec,
     FluxFilterState,
     FluxFilterValue,
     FluxFilterValueSingle
 } from './filter';
 
 export type {
+    FluxFormInputBaseProps,
     FluxFormSelectEntry,
     FluxFormSelectGroup,
     FluxFormSelectOption,
     FluxFormSelectOptions,
     FluxFormSelectValue,
-    FluxFormSelectValueSingle
+    FluxFormSelectValueSingle,
+    FluxFormTreeViewSelectOption,
+    FluxFormTreeViewSelectValue,
+    FluxFormTreeViewSelectValueSingle
 } from './form';
 
 export type {
@@ -56,3 +77,31 @@ export type {
     FluxSnackbarObject,
     FluxTooltipObject
 } from './notify';
+
+export type {
+    FluxStatisticsChange,
+    FluxStatisticsChartAreaSeries,
+    FluxStatisticsChartBarSeries,
+    FluxStatisticsChartBoxPlotPoint,
+    FluxStatisticsChartBoxPlotSeries,
+    FluxStatisticsChartBubblePoint,
+    FluxStatisticsChartBubbleSeries,
+    FluxStatisticsChartCandlestickPoint,
+    FluxStatisticsChartCandlestickSeries,
+    FluxStatisticsChartCartesianSeries,
+    FluxStatisticsChartCategoryPoint,
+    FluxStatisticsChartColor,
+    FluxStatisticsChartGaugeSeries,
+    FluxStatisticsChartHeatmapPoint,
+    FluxStatisticsChartHeatmapSeries,
+    FluxStatisticsChartLineSeries,
+    FluxStatisticsChartMixedSeries,
+    FluxStatisticsChartPieSlice,
+    FluxStatisticsChartRadarIndicator,
+    FluxStatisticsChartRadarSeries,
+    FluxStatisticsChartScatterPoint,
+    FluxStatisticsChartScatterSeries,
+    FluxStatisticsChartTreemapNode,
+    FluxStatisticsChartTreemapSeries,
+    FluxStatisticsPercentageBarItemObject
+} from './statistics';

package/src/statistics.ts

@@ -0,0 +1,146 @@
+import type { FluxColor, FluxIconName } from './common';
+
+export type FluxStatisticsChange = {
+    readonly color?: FluxColor;
+    readonly icon?: FluxIconName;
+    readonly value: string | number;
+};
+
+export type FluxStatisticsChartColor = FluxColor | `#${string}` | `var(--${string})`;
+
+export interface FluxStatisticsPercentageBarItemObject {
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+    readonly label: string;
+    readonly value: number;
+    readonly displayValue?: string | number;
+}
+
+export interface FluxStatisticsChartCategoryPoint {
+    readonly label?: string;
+    readonly value: number;
+}
+
+export interface FluxStatisticsChartCartesianSeries {
+    readonly name?: string;
+    readonly data: readonly (number | FluxStatisticsChartCategoryPoint)[];
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export type FluxStatisticsChartLineSeries = FluxStatisticsChartCartesianSeries;
+export type FluxStatisticsChartAreaSeries = FluxStatisticsChartCartesianSeries;
+export type FluxStatisticsChartBarSeries = FluxStatisticsChartCartesianSeries;
+
+export interface FluxStatisticsChartMixedSeries extends FluxStatisticsChartCartesianSeries {
+    readonly type: 'line' | 'area' | 'bar';
+}
+
+export interface FluxStatisticsChartPieSlice {
+    readonly label: string;
+    readonly value: number;
+    readonly formatted?: string;
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartRadarIndicator {
+    readonly name: string;
+    readonly max?: number;
+}
+
+export interface FluxStatisticsChartRadarSeries {
+    readonly name?: string;
+    readonly values: readonly number[];
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartScatterPoint {
+    readonly x: number;
+    readonly y: number;
+}
+
+export interface FluxStatisticsChartScatterSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartScatterPoint[];
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartBubblePoint extends FluxStatisticsChartScatterPoint {
+    readonly size: number;
+}
+
+export interface FluxStatisticsChartBubbleSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartBubblePoint[];
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartCandlestickPoint {
+    readonly label?: string;
+    readonly open: number;
+    readonly close: number;
+    readonly low: number;
+    readonly high: number;
+}
+
+export interface FluxStatisticsChartCandlestickSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartCandlestickPoint[];
+    readonly positiveColor?: FluxStatisticsChartColor;
+    readonly negativeColor?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartBoxPlotPoint {
+    readonly label?: string;
+    readonly min: number;
+    readonly q1: number;
+    readonly median: number;
+    readonly q3: number;
+    readonly max: number;
+}
+
+export interface FluxStatisticsChartBoxPlotSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartBoxPlotPoint[];
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartHeatmapPoint {
+    readonly x: string | number;
+    readonly y: string | number;
+    readonly value: number;
+    readonly formatted?: string;
+}
+
+export interface FluxStatisticsChartHeatmapSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartHeatmapPoint[];
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartTreemapNode {
+    readonly name: string;
+    readonly value?: number;
+    readonly color?: FluxStatisticsChartColor;
+    readonly children?: readonly FluxStatisticsChartTreemapNode[];
+}
+
+export interface FluxStatisticsChartTreemapSeries {
+    readonly name?: string;
+    readonly data: readonly FluxStatisticsChartTreemapNode[];
+    readonly icon?: FluxIconName;
+}
+
+export interface FluxStatisticsChartGaugeSeries {
+    readonly name: string;
+    readonly value: number;
+    readonly radius?: number;
+    readonly color?: FluxStatisticsChartColor;
+    readonly icon?: FluxIconName;
+}