@ostack.tech/ui 0.1.0

package/dist/types/utils/useCombinedRef.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+/**
+ * Combines multiple references into a single stable callback reference while
+ * respecting React's rules for references.
+ *
+ * @param refs References to combine.
+ * @returns Stable callback reference.
+ */
+export declare function useCombinedRef<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T>;

package/dist/types/utils/useConstant.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hook for creating a value exactly once.
+ *
+ * @param fn Function which created the value to return.
+ * @returns Value created on the first render of the hook.
+ */
+export declare function useConstant<T>(fn: () => T): T;

package/dist/types/utils/useControllableState.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+/** Helper hook to handle controlled or uncontrolled values. */
+export declare function useControllableState<T>(initialValue: T | (() => T), controlledValue: T | undefined): [T, React.Dispatch<React.SetStateAction<T>>];

package/dist/types/utils/useCssVars.d.ts

@@ -0,0 +1,47 @@
+import { type PrefixFn } from "../providers/PrefixProvider";
+/** Options available to the {@link useCssVars} hook. */
+export interface UseCssVarsOptions {
+    prefix?: PrefixFn;
+}
+/** Result of the {@link useCssVars} hook. */
+export interface UseCssVarsResult {
+    /**
+     * Returns the name of a CSS variable prefixed by the component library's
+     * prefix.
+     *
+     * @example
+     *
+     * ```typescript
+     * cssVarName("color"); // returns "--[prefix]-color"
+     * ```
+     */
+    cssVarName: (name: string) => string;
+    /**
+     * Returns a CSS variable with the given name, prefixed by the component
+     * library's prefix.
+     *
+     * @example
+     *
+     * ```typescript
+     * cssVar("color"); // returns "var(--[prefix]-color)"
+     * cssVar("size", "10px"); // returns "var(--[prefix]-size, 10px)"
+     * ```
+     */
+    cssVar: (name: string, fallback?: unknown) => string;
+    /**
+     * Returns an object used to set a CSS variable with the given name, prefixed
+     * by the component library's prefix.
+     *
+     * @example
+     *
+     * ```typescript
+     * cssVarStyle("color", "red"); // returns {"--[prefix]-color": "red"}
+     * cssVarStyle("size", undefined); // returns undefined
+     * ```
+     */
+    cssVarStyle: (name: string, value: unknown) => Record<string, string> | undefined;
+    /** Returns the name of a CSS variable to use for a CSS space toggle. */
+    cssToggler: (value: boolean, customPrefix?: string) => string;
+}
+/** Hook providing access to CSS variable utilities. */
+export declare function useCssVars(options?: UseCssVarsOptions): UseCssVarsResult;

package/dist/types/utils/useDateTransformer.d.ts

@@ -0,0 +1,53 @@
+import { type Locale } from "date-fns";
+/** Default short date format. */
+export declare const DEFAULT_SHORT_DATE_FORMAT = "yyyy-MM-dd";
+/** Default full date format. */
+export declare const DEFAULT_FULL_DATE_FORMAT = "EEEE, d MMMM yyyy";
+/** Options of the `useDateTransformer` hook. */
+export interface DateTransformerOptions {
+    /** `date-fns` locale to format dates. */
+    locale?: Locale;
+    /**
+     * Short format of the date, as supported by
+     * [`date-fns`](https://date-fns.org/docs/format).
+     */
+    shortFormat?: string;
+    /**
+     * Full format of the date, as supported by
+     * [`date-fns`](https://date-fns.org/docs/format).
+     */
+    fullFormat?: string;
+}
+/** Available formatting widths. */
+export type DateFormatWidth = "short" | "full";
+/** Optons of the date formatter. */
+export interface DateFormatterOptions {
+    /**
+     * Formatted date width.
+     *
+     * @default short
+     */
+    width?: DateFormatWidth;
+}
+/** Optons of the date parser. */
+export interface DateParserOptions {
+    /**
+     * Formatted date width.
+     *
+     * @default short
+     */
+    width?: DateFormatWidth;
+}
+/** Date transformer. */
+export interface DateTransformer {
+    /** Function used to strictly parse a string as a date. */
+    parse: (formattedDate: string, options?: DateParserOptions) => Date | null;
+    /** Function used to format the date as a string. */
+    format: (date: string | number | Date | null, options?: DateFormatterOptions) => string;
+}
+/**
+ * Hook returning functions that can be used to transform a date according to
+ * the current locale. By default, the returned functions transform a date in
+ * the same way a `DateInput` would.
+ */
+export declare function useDateTransformer({ locale: dateFnsLocale, shortFormat, fullFormat, }?: DateTransformerOptions): DateTransformer;

package/dist/types/utils/useIntersectionObserver.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook wrapping an `IntersectionObserver` which tracks the intersection ratio
+ * of an element.
+ */
+export declare function useIntersectionObserver<T extends Element = Element>(element: T | null, onIntersectionEntryChange: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit): void;

package/dist/types/utils/useLatestValues.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hook providing a stable identity object containing the latest values. These
+ * values should **not** be accessed during render time.
+ *
+ * @param values Object containing all values.
+ * @returns Stable identity object containing said values.
+ */
+export declare function useLatestValues<T extends Record<keyof T, unknown>>(values: T): T;

package/dist/types/utils/useLayoutEffect.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+/** `useLayoutEffect` hook which performs a noop when run on the server. */
+export declare const useLayoutEffect: typeof React.useLayoutEffect;

package/dist/types/utils/useMeasure.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook that tracks the dimensions of an HTML element using the Resize Observer
+ * API.
+ */
+export declare function useMeasure<T extends Element = Element>(element: T | null, setMeasurement: (measurement: DOMRectReadOnly | undefined) => void): void;

package/dist/types/utils/useMediaQuery.d.ts

@@ -0,0 +1,12 @@
+/** Options for the `useMediaQuery` hook. */
+export interface UseMediaQueryOptions {
+    /** Default match when `matchMedia` is unavailable. */
+    defaultMatches?: boolean;
+    /** `matchMedia` implementation (e.g. for tests). */
+    matchMedia?: typeof window.matchMedia;
+}
+/**
+ * Hook exposing a CSS media query to React. Returns whether the media query
+ * matches or not.
+ */
+export declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;

package/dist/types/utils/useNumericTransformer.d.ts

@@ -0,0 +1,60 @@
+/** Styles of digit grouping. */
+export type GroupingStyle = "thousand" | "lakh" | "wan";
+/** Options of the `useNumericTransformer` hook. */
+export interface NumericTransformerOptions {
+    /**
+     * Whether the value should always represent an integer, even when it contains
+     * a scale. Note that in this case, the scale must be known (i.e. `scale` must
+     * not be `undefined`).
+     */
+    valueIsInteger?: boolean;
+    /**
+     * Specifies the number of digits allowed after the decimal separator. When
+     * not specified, the scale has no limits.
+     *
+     * @default null
+     */
+    scale?: number;
+    /**
+     * Whether to always add trailing zeros to match the given `scale`. Defaults
+     * to `false` when `scale` is `null` and `true` otherwise.
+     */
+    fixedScale?: boolean;
+    /**
+     * Character to use as a decimal separator. Defaults to the locale's
+     * separator.
+     */
+    decimalSeparator?: string;
+    /**
+     * Whether to group the integer part of the number.
+     *
+     * @default false
+     */
+    groupDigits?: boolean;
+    /** Style of grouping. Defaults to the locale's default style. */
+    groupingStyle?: GroupingStyle;
+    /**
+     * Character to use to separate the groups of digits. Defaults to the locale's
+     * separator.
+     */
+    groupSeparator?: string;
+    /** Prefix to add to the input's text. */
+    prefix?: string;
+    /** Suffix to add to the input's text. */
+    suffix?: string;
+}
+/** Numeric transformer. */
+export interface NumericTransformer {
+    /** Function used to parse a formatted numeric value into a numeric string. */
+    parse: (formattedValue: string, options?: NumericTransformerOptions) => string;
+    /** Function used to format a numeric value. */
+    format: (value: string | number | null | undefined, options?: NumericTransformerOptions) => string;
+}
+/** Hook returning functions that can be used to transform a numeric value. */
+export declare function useNumericTransformer({ valueIsInteger, scale, fixedScale, decimalSeparator, groupDigits, groupingStyle, groupSeparator, prefix, suffix, }?: NumericTransformerOptions): NumericTransformer;
+/** Validates numeric transformer options. */
+export declare function validateNumericTransformerOptions({ valueIsInteger, scale, decimalSeparator, groupSeparator, }?: NumericTransformerOptions): void;
+/** Transforms a formatted numeric value into its numeric string representation. */
+export declare function parseNumericValue(formattedValue: string, options?: NumericTransformerOptions): string;
+/** Formats a numeric value. */
+export declare function formatNumericValue(value: string | number | null | undefined, options?: NumericTransformerOptions): string;

package/dist/types/utils/useResponsiveValues.d.ts

@@ -0,0 +1,31 @@
+import { type Breakpoint } from "./breakpoints.ts";
+import { type UseCssVarsOptions } from "./useCssVars.ts";
+/** Value allowing for different values depending on the current breakpoint. */
+export type Responsive<T = unknown> = T | Partial<Record<Breakpoint, T>>;
+/** Options available to the {@link useResponsiveValues} hook. */
+export type UseResponsiveValuesOptions = UseCssVarsOptions;
+/** Result of the {@link useResponsiveValues} hook. */
+export interface UseResponsiveValuesResult {
+    /**
+     * Returns an object of CSS variables for multiple responsive values, together
+     * with data attributes specifying which breakpoints of each value have an
+     * associated CSS variable.
+     */
+    responsiveValuesToCssVarsAndDataAttrs: <T extends Record<string, unknown>, TMappers extends {
+        [TKey in keyof T]: (value: T[TKey] extends Responsive<infer TValue> | undefined ? TValue : never) => unknown;
+    }>(componentName: string, values: T, mappers?: Partial<TMappers>) => {
+        cssVars: Record<string, string | undefined>;
+        dataAttrs: Record<string, string | undefined>;
+    };
+    /**
+     * Returns an object of CSS variables for a responsive value, together with
+     * data attributes specifying which breakpoints have an associated CSS
+     * variable.
+     */
+    responsiveValueToCssVarsAndDataAttrs: <T>(componentName: string, varName: string, value?: Responsive<T>, mapper?: (value: T) => unknown) => {
+        cssVars: Record<string, string | undefined>;
+        dataAttrs: Record<string, string | undefined>;
+    };
+}
+/** Hook providing access to responsive value utilities. */
+export declare function useResponsiveValues(options?: UseResponsiveValuesOptions): UseResponsiveValuesResult;

package/dist/types/utils/useScrollPosition.d.ts

@@ -0,0 +1,15 @@
+/** Position of the scroll in relation to each direction. */
+export interface ScrollPosition<T extends Element = Element> {
+    target: T | null;
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Result of the `useScrollPosition` hook. */
+export type UseScrollPositionResult<T extends Element = Element> = [
+    setElement: (element: T) => void,
+    scrollPosition: ScrollPosition | undefined
+];
+/** Hook that tracks the position of an element's scroll. */
+export declare function useScrollPosition<T extends Element = Element>(element: T | null, setScrollPosition: (scrollPosition: ScrollPosition | undefined) => void): void;

package/dist/types/utils/useScrollbarSize.d.ts

@@ -0,0 +1,8 @@
+/** Scrollbar measurements. */
+interface ScrollbarMeasurements {
+    height: number;
+    width: number;
+}
+/** Hook returning the measurements of the browser's scrollbars. */
+export declare function useScrollbarSize(): ScrollbarMeasurements;
+export {};

package/dist/types/utils/useSpacing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Function used to obtain a CSS values representing a size based on the theme's
+ * “space” value.
+ */
+export type SpacingFn = (...values: number[]) => string;
+/** Returns a CSS value representing a size based on the theme's "space" value. */
+export declare function useSpacing(): SpacingFn;

package/dist/types/utils/warnOnce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Emit a warning once.
+ *
+ * @param message Warning message.
+ */
+export declare function warnOnce(message: string): void;

package/dist/types/utils/zustandUtils.d.ts

@@ -0,0 +1,4 @@
+/** Empty Zustand store. */
+export declare const EMPTY_STORE: import("zustand").StoreApi<any>;
+/** Function used within a Zustand store to hold computed state. */
+export declare function computed<const TDeps extends readonly unknown[] = unknown[], TResult = unknown>(depsFn: () => TDeps, computeFn: (...deps: TDeps) => TResult): () => TResult;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@ostack.tech/ui",
+  "description": "ostack/UI component library.",
+  "version": "0.1.0",
+  "homepage": "https://ui.ostack.tech/",
+  "author": {
+    "name": "Opensoft",
+    "url": "https://opensoft.pt/en/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://bitbucket.org/opensoftgitrepo/ostack-ui.git",
+    "directory": "packages/ui/"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=10"
+  },
+  "main": "dist/ostack-ui.cjs",
+  "types": "dist/types/index.d.ts",
+  "sass": "scss/index.scss",
+  "style": "dist/ostack-ui.css",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/ostack-ui.js",
+      "require": "./dist/ostack-ui.cjs"
+    },
+    "./css": "./dist/ostack-ui.css",
+    "./scss": "./scss/index.scss",
+    "./scss/*": "./scss/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "scss"
+  ],
+  "scripts": {
+    "clean": "rimraf dist scss",
+    "build": "npm run build:js && npm run build:css",
+    "build:js": "vite build && tsc -b tsconfig.build.json",
+    "build:css": "npm run copy-scss && sass -I ../../node_modules scss/index.scss dist/ostack-ui.css",
+    "copy-scss": "cpy 'src/**/*.scss' '!src/**/*.stories.scss' scss"
+  },
+  "dependencies": {
+    "@fortawesome/react-fontawesome": "^3.1.0",
+    "@tanstack/react-virtual": "^3.13.12",
+    "cmdk": "^1.1.1",
+    "from-exponential": "^1.1.1",
+    "radix-ui": "^1.4.3",
+    "react-day-picker": "^9.11.1",
+    "react-error-boundary": "^6.0.0",
+    "react-number-format": "^5.4.4",
+    "tinykeys": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@fortawesome/fontawesome-svg-core": "^6.2.0 || ^7.0.0",
+    "@fortawesome/free-regular-svg-icons": "^6.2.0 || ^7.0.0",
+    "@fortawesome/free-solid-svg-icons": "^6.2.0 || ^7.0.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^18.0.0 || ^19.0.0",
+    "date-fns": "^4.1.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "zustand": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "@types/react-dom": {
+      "optional": true
+    }
+  }
+}

package/scss/_utils.scss

@@ -0,0 +1,59 @@
+// Base variables
+@forward "scss/base-variables";
+
+// Utils
+@forward "scss/utils/animation";
+@forward "scss/utils/breakpoints";
+@forward "scss/utils/declare-var";
+@forward "scss/utils/responsive-values";
+@forward "scss/utils/space-toggle";
+@forward "scss/utils/spacing";
+@forward "scss/utils/spinner";
+@forward "scss/utils/transition";
+
+// Component/placeholder variables
+@forward "scss/placeholders/button/button-variables";
+@forward "scss/placeholders/control/control-variables";
+@forward "components/Label/Label-variables";
+@forward "scss/placeholders/checkable/checkable-variables";
+@forward "scss/placeholders/checkable-group/checkable-group-variables";
+@forward "scss/placeholders/menu/menu-variables";
+@forward "scss/placeholders/notification/notification-variables";
+@forward "scss/placeholders/popover/popover-variables";
+@forward "components/Alert/Alert-variables";
+@forward "components/Button/Button-variables";
+@forward "components/ButtonGroup/ButtonGroup-variables";
+@forward "components/Calendar/Calendar-variables";
+@forward "components/Card/Card-variables";
+@forward "components/Checkbox/Checkbox-variables";
+@forward "components/CloseButton/CloseButton-variables";
+@forward "components/Code/Code-variables";
+@forward "components/Collapsible/Collapsible-variables";
+@forward "components/Dialog/Dialog-variables";
+@forward "components/CommandMenu/CommandMenu-variables";
+@forward "components/Container/Container-variables";
+@forward "components/ControlAddon/ControlAddon-variables";
+@forward "components/DateRangeInput/DateRangeInput-variables";
+@forward "components/ControlCode/ControlCode-variables";
+@forward "components/DropdownMenu/DropdownMenu-variables";
+@forward "components/FeedbackList/FeedbackList-variables";
+@forward "components/FeedbackPopover/FeedbackPopover-variables";
+@forward "components/FieldGroup/FieldGroup-variables";
+@forward "components/Heading/Heading-variables";
+@forward "components/HelperText/HelperText-variables";
+@forward "components/Feedback/Feedback-variables";
+@forward "components/Icon/Icon-variables";
+@forward "components/IconButton/IconButton-variables";
+@forward "components/Input/Input-variables";
+@forward "components/Link/Link-variables";
+@forward "components/Mark/Mark-variables";
+@forward "components/Overlay/Overlay-variables";
+@forward "components/RadioGroup/Radio-variables";
+@forward "components/Root/Root-variables";
+@forward "components/Select/Select-variables";
+@forward "components/Stack/Stack-variables";
+@forward "components/Stepper/Stepper-variables";
+@forward "components/Table/Table-variables";
+@forward "components/Tabs/Tabs-variables";
+@forward "components/Tag/Tag-variables";
+@forward "components/Tooltip/Tooltip-variables";

package/scss/components/Alert/_Alert-variables.scss

@@ -0,0 +1,5 @@
+@use "../../scss/utils/spacing" as *;
+
+$alert-margin-bottom: spacing(4);
+
+$alert-collapsible-animation-duration: 0.1s;

package/scss/components/Alert/_Alert.scss

@@ -0,0 +1,56 @@
+@use "sass:math";
+
+@use "Alert-variables" as *;
+@use "../../scss/base-variables" as *;
+@use "../../scss/placeholders/notification/notification" as *;
+@use "../../scss/placeholders/notification/notification-variables" as *;
+@use "../../scss/utils/animation" as *;
+
+.#{$prefix}alert {
+  $checkbox: ".#{$prefix}checkbox";
+  $radio: ".#{$prefix}radio";
+
+  @extend %#{$prefix}notification;
+
+  &__container {
+    width: 100%;
+    overflow: hidden;
+  }
+
+  &__content {
+    overflow: auto;
+  }
+
+  &__icon {
+    @extend %#{$prefix}notification__icon;
+  }
+
+  &__title {
+    @extend %#{$prefix}notification__title;
+  }
+
+  &__action-container {
+    @extend %#{$prefix}notification__action-container;
+  }
+
+  &__close-button {
+    @extend %#{$prefix}notification__close-button;
+  }
+
+  @each $variant in $notification-variants {
+    &--#{$variant} {
+      @extend %#{$prefix}notification--#{$variant};
+    }
+  }
+
+  #{$checkbox},
+  #{$radio} {
+    &:not([data-readonly]) {
+      background-color: var(--#{$prefix}background-color) !important;
+    }
+
+    &__label {
+      color: inherit !important;
+    }
+  }
+}