@geniee-inc/sfa-kit 1.6.0

package/src/lib/provider/SfaProvider.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import type { SfaApiMode, SfaAuth, SfaClientInterface } from './types';
+export interface SfaContextValue {
+    readonly client: SfaClientInterface;
+    readonly auth: SfaAuth | undefined;
+    readonly mode: SfaApiMode;
+    readonly organizationId: string | undefined;
+    /** When true, mutation hooks (create/update/delete) throw instead of executing. */
+    readonly readOnly: boolean;
+}
+export declare const SfaContext: import("react").Context<SfaContextValue | null>;
+interface SfaProviderProps {
+    readonly apiBase: string;
+    readonly auth?: SfaAuth;
+    readonly mode?: SfaApiMode;
+    readonly organizationId?: string;
+    readonly onAuthError?: () => void;
+    /**
+     * Disable mutation hooks (create/update/delete). Defaults to false.
+     *
+     * Set to true in JAI Studio standalone preview mode. In preview, the
+     * DevToolbar shows "Preview Mode" and the user authenticates with real
+     * credentials, but the session is for testing page layout, not for
+     * modifying production data. Without this guard, a generated page with
+     * write hooks would silently create/update/delete real records during
+     * preview, which users would not expect.
+     *
+     * When the same page is embedded in SFA/CRM (production), readOnly
+     * stays false and writes work normally.
+     */
+    readonly readOnly?: boolean;
+    readonly children: ReactNode;
+}
+/**
+ * @description Wraps the page and provides an SfaClient to all child components via context.
+ */
+export declare function SfaProvider({ apiBase, auth, mode, organizationId, onAuthError, readOnly, children, }: SfaProviderProps): JSX.Element;
+export {};

package/src/lib/provider/SfaProvider.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useMemo, useRef } from 'react';
+import { SfaClient } from './SfaClient';
+function detectMode(apiBase) {
+    // An absolute HTTP(S) URL points at an API endpoint (including a local
+    // keystone at localhost/127.0.0.1) -> direct. A relative path relays
+    // through the hosting app -> proxy.
+    if (/^https?:\/\//i.test(apiBase))
+        return 'direct';
+    return 'proxy';
+}
+export const SfaContext = createContext(null);
+/**
+ * @description Wraps the page and provides an SfaClient to all child components via context.
+ */
+export function SfaProvider({ apiBase, auth, mode, organizationId, onAuthError, readOnly = false, children, }) {
+    const resolvedMode = mode !== null && mode !== void 0 ? mode : detectMode(apiBase);
+    const resolvedOrgId = organizationId;
+    // Depend on the token string (primitive, compared by value) instead of the
+    // auth object reference, so inline `auth={{ accessToken }}` doesn't cause
+    // SfaClient re-creation on every parent render.
+    const accessToken = auth === null || auth === void 0 ? void 0 : auth.accessToken;
+    // Use a ref for onAuthError so updates don't trigger client re-creation.
+    const onAuthErrorRef = useRef(onAuthError);
+    onAuthErrorRef.current = onAuthError;
+    const value = useMemo(() => {
+        const stableAuth = accessToken ? { accessToken } : undefined;
+        const client = new SfaClient({
+            apiBase,
+            auth: stableAuth,
+            mode: resolvedMode,
+            organizationId: resolvedOrgId,
+            onAuthError: () => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef); },
+        });
+        return {
+            client,
+            auth: stableAuth,
+            mode: resolvedMode,
+            organizationId: resolvedOrgId,
+            readOnly,
+        };
+    }, [apiBase, accessToken, resolvedMode, resolvedOrgId, readOnly]);
+    return _jsx(SfaContext.Provider, { value: value, children: children });
+}

package/src/lib/provider/types.d.ts

@@ -0,0 +1,184 @@
+export interface SfaAuth {
+    readonly accessToken: string;
+}
+export type SfaApiMode = 'direct' | 'proxy';
+export interface SfaClientConfig {
+    readonly apiBase: string;
+    readonly auth?: SfaAuth;
+    readonly mode: SfaApiMode;
+    readonly organizationId?: string;
+    readonly onAuthError?: () => void;
+}
+/**
+ * @description Normalized field kinds aligned with keystone's 10-type model.
+ * Components render based on these kinds, not the raw Chikyu type strings.
+ */
+export type SfaFieldKind = 'text' | 'number' | 'date' | 'datetime' | 'single_choice' | 'multi_choice' | 'reference' | 'user_reference' | 'computed' | 'record_type';
+/**
+ * @description A normalized field value. Components use `kind` to decide
+ * rendering and `label` for display. The `value` is the raw stored value.
+ * This shape works for both Chikyu (caption -> label) and keystone
+ * (coded.label -> label, scalar has label=null).
+ */
+export interface SfaFieldValue {
+    readonly kind: SfaFieldKind;
+    readonly value: unknown;
+    readonly label: string | null;
+}
+export type SfaFieldValueMapping = Readonly<Record<string, SfaFieldValue>>;
+export interface SfaRecord {
+    readonly record_id: string;
+    readonly collection_name: string;
+    readonly fields: SfaFieldValueMapping;
+    readonly titleFields: readonly string[];
+    /** Pre-built display title from keystone. Preferred over titleFields when present. */
+    readonly title?: string | null;
+    /** Opaque version token for optimistic locking (keystone ETag value). */
+    readonly version?: string | null;
+    readonly permissions: {
+        readonly canEdit: boolean;
+        readonly canDelete: boolean;
+    };
+}
+export interface SfaListResponse {
+    readonly items: readonly SfaRecord[];
+    readonly totalCount: number;
+    readonly hasMore: boolean;
+    readonly pageIndex: number;
+    /** Cursor for fetching the next page (keystone cursor-based pagination). */
+    readonly nextCursor?: string | null;
+    /** Cursor for fetching the previous page (keystone cursor-based pagination). */
+    readonly prevCursor?: string | null;
+}
+export interface SfaClientInterface {
+    get(collection: string, recordId: string): Promise<SfaRecord>;
+    list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
+    describe(objectKey: string): Promise<SfaDescribeResult>;
+    listObjects(): Promise<SfaObjectCatalog>;
+    listFieldTypes(): Promise<SfaFieldTypeCatalog>;
+    create(collection: string, fields: Record<string, unknown>, options?: SfaCreateOptions): Promise<SfaRecord>;
+    update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
+    delete(collection: string, recordId: string, version: string): Promise<void>;
+}
+/**
+ * @description Options for creating a record. The idempotency key prevents
+ * duplicate creates if the same request is retried.
+ */
+export interface SfaCreateOptions {
+    readonly idempotencyKey?: string;
+}
+/**
+ * @description A single per-field validation error from a 422 response.
+ */
+export interface SfaFieldError {
+    readonly field: string;
+    readonly code: string;
+    readonly message: string;
+}
+export interface SfaListParams {
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly sortBy?: string;
+    readonly sortOrder?: 'asc' | 'desc';
+    readonly filter?: Record<string, unknown>;
+    /** Opaque cursor for keystone cursor-based pagination. Takes precedence over offset. */
+    readonly cursor?: string;
+}
+export type SfaObjectOrigin = 'standard' | 'custom';
+export type SfaRelationshipKind = 'association' | 'master_detail';
+export type SfaCardinality = 'one' | 'many';
+export interface SfaFieldOption {
+    readonly value: string;
+    readonly label: string;
+    readonly order?: number;
+    readonly hidden?: boolean;
+}
+/**
+ * @description One field in an object's schema. Provides everything needed
+ * to render, validate, and filter by this field.
+ */
+export interface SfaFieldDescriptor {
+    readonly key: string;
+    readonly label: string;
+    readonly kind: SfaFieldKind;
+    readonly description: string | null;
+    readonly required: boolean;
+    readonly readOnly: boolean;
+    readonly order: number;
+    readonly section: string | null;
+    readonly filterable: boolean;
+    readonly sortable: boolean;
+    readonly options?: readonly SfaFieldOption[];
+    readonly targetObject?: string;
+    readonly cardinality?: SfaCardinality;
+    readonly displayField?: string;
+}
+/**
+ * @description A directed relationship from one object to another.
+ */
+export interface SfaRelationDescriptor {
+    readonly name: string;
+    readonly target: string;
+    readonly cardinality: SfaCardinality;
+    readonly kind: SfaRelationshipKind;
+    readonly viaField: string;
+}
+export interface SfaObjectPermissions {
+    readonly readable: boolean;
+    readonly creatable: boolean;
+    readonly updatable: boolean;
+    readonly deletable: boolean;
+}
+/**
+ * @description Lightweight object summary from the catalog (GET /v1/objects).
+ */
+export interface SfaObjectSummary {
+    readonly key: string;
+    readonly label: string;
+    readonly origin: SfaObjectOrigin;
+    readonly primaryDisplayField: string | null;
+    readonly relationships: readonly SfaRelationDescriptor[];
+}
+/**
+ * @description Full object description from describe (GET /v1/objects/{key}).
+ */
+export interface SfaObjectDetail {
+    readonly key: string;
+    readonly label: string;
+    readonly origin: SfaObjectOrigin;
+    readonly primaryDisplayField: string | null;
+    readonly fields: readonly SfaFieldDescriptor[];
+    readonly relationships: readonly SfaRelationDescriptor[];
+    readonly permissions: SfaObjectPermissions;
+}
+export interface SfaDescribeResult {
+    readonly object: SfaObjectDetail;
+}
+export interface SfaObjectCatalog {
+    readonly objects: readonly SfaObjectSummary[];
+}
+export type SfaFilterOperator = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'within_relative' | 'contains' | 'starts_with' | 'ends_with' | 'in' | 'not_in' | 'is_null' | 'is_not_null';
+/**
+ * @description Self-describing definition of one field kind from the
+ * static catalog (GET /v1/field-types). Tells the consumer what a kind
+ * means, how its value reads, and what filter operators it supports.
+ */
+export interface SfaFieldTypeDescriptor {
+    readonly kind: SfaFieldKind;
+    readonly summary: string;
+    readonly valueShape: string;
+    readonly multiValued: boolean;
+    readonly editableByDefault: boolean;
+    readonly hasOptions: boolean;
+    readonly referencesObject: boolean;
+    readonly operators: readonly SfaFilterOperator[];
+}
+export interface SfaFieldTypeCatalog {
+    readonly fieldTypes: readonly SfaFieldTypeDescriptor[];
+}
+export type FieldGroupLayout = '1-col' | '2-col' | '3-col';
+export interface FieldGroupSpec {
+    readonly title?: string;
+    readonly layout?: FieldGroupLayout;
+    readonly fields: readonly string[];
+}

package/src/lib/provider/types.js

@@ -0,0 +1 @@
+export {};

package/src/lib/provider/useSfaClient.d.ts

@@ -0,0 +1,11 @@
+import type { SfaContextValue } from './SfaProvider';
+import type { SfaClientInterface } from './types';
+/**
+ * @description Returns the SfaClient instance from the nearest SfaProvider.
+ */
+export declare function useSfaClient(): SfaClientInterface;
+/**
+ * @description Returns the full SfaProvider context including the readOnly flag.
+ * Used by mutation hooks to guard against writes in preview mode.
+ */
+export declare function useSfaContext(): SfaContextValue;

package/src/lib/provider/useSfaClient.js

@@ -0,0 +1,24 @@
+import { useContext } from 'react';
+import { ERR_NO_PROVIDER } from '../errors';
+import { SfaContext } from './SfaProvider';
+/**
+ * @description Returns the SfaClient instance from the nearest SfaProvider.
+ */
+export function useSfaClient() {
+    const context = useContext(SfaContext);
+    if (context == null) {
+        throw new Error(ERR_NO_PROVIDER);
+    }
+    return context.client;
+}
+/**
+ * @description Returns the full SfaProvider context including the readOnly flag.
+ * Used by mutation hooks to guard against writes in preview mode.
+ */
+export function useSfaContext() {
+    const context = useContext(SfaContext);
+    if (context == null) {
+        throw new Error(ERR_NO_PROVIDER);
+    }
+    return context;
+}

package/src/lib/theme.d.ts

@@ -0,0 +1,55 @@
+import type { CSSProperties } from 'react';
+/**
+ * @description All colors use CSS custom properties with GENIEE SFA defaults as fallbacks.
+ * Override any color by setting the CSS variable on a parent element:
+ *   :root { --sfa-primary: #FF0000; }
+ *   <div style={{ '--sfa-primary': '#FF0000' }}>...</div>
+ */
+export declare const color: {
+    readonly primary: "var(--sfa-primary, #3867D1)";
+    readonly primaryHover: "var(--sfa-primary-hover, #4E7EF5)";
+    readonly primaryLight: "var(--sfa-primary-light, #F0F5FF)";
+    readonly primaryDark: "var(--sfa-primary-dark, #203EAB)";
+    readonly error: "var(--sfa-error, #ED5C5C)";
+    readonly errorHover: "var(--sfa-error-hover, #FF8282)";
+    readonly errorLight: "var(--sfa-error-light, #FEF0F0)";
+    readonly success: "var(--sfa-success, #A3C848)";
+    readonly warning: "var(--sfa-warning, #F2B45E)";
+    readonly white: "#FFFFFF";
+    readonly black: "#000000";
+    readonly textPrimary: "var(--sfa-text-primary, #313542)";
+    readonly textSecondary: "var(--sfa-text-secondary, #838A98)";
+    readonly textMuted: "var(--sfa-text-muted, #ACB0BA)";
+    readonly textPlaceholder: "var(--sfa-text-placeholder, #C1C1C1)";
+    readonly border: "var(--sfa-border, #D6D9DD)";
+    readonly borderLight: "var(--sfa-border-light, #F2F2F2)";
+    readonly divider: "var(--sfa-divider, #F2F2F2)";
+    readonly bgDefault: "var(--sfa-bg-default, #F7F8FA)";
+    readonly bgSurface: "var(--sfa-bg-surface, #FFFFFF)";
+    readonly bgHover: "var(--sfa-bg-hover, rgba(0, 0, 0, 0.03))";
+    readonly bgDisabled: "var(--sfa-bg-disabled, rgba(0, 0, 0, 0.1))";
+};
+export declare const font: {
+    readonly family: "var(--sfa-font-family, 'Noto Sans JP', 'Roboto', 'Helvetica', 'Arial', sans-serif)";
+    readonly sizeXs: 11;
+    readonly sizeSm: 12;
+    readonly sizeMd: 13;
+    readonly sizeLg: 14;
+    readonly sizeXl: 16;
+    readonly sizeTitle: 18;
+    readonly weightRegular: 400;
+    readonly weightMedium: 700;
+};
+export declare const space: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 16;
+    readonly lg: 24;
+    readonly xl: 32;
+};
+export declare const radius: {
+    readonly sm: 4;
+    readonly md: 4;
+};
+export declare const baseContainerStyle: CSSProperties;
+export declare const baseButtonStyle: CSSProperties;

package/src/lib/theme.js

@@ -0,0 +1,68 @@
+/**
+ * @description All colors use CSS custom properties with GENIEE SFA defaults as fallbacks.
+ * Override any color by setting the CSS variable on a parent element:
+ *   :root { --sfa-primary: #FF0000; }
+ *   <div style={{ '--sfa-primary': '#FF0000' }}>...</div>
+ */
+export const color = {
+    primary: 'var(--sfa-primary, #3867D1)',
+    primaryHover: 'var(--sfa-primary-hover, #4E7EF5)',
+    primaryLight: 'var(--sfa-primary-light, #F0F5FF)',
+    primaryDark: 'var(--sfa-primary-dark, #203EAB)',
+    error: 'var(--sfa-error, #ED5C5C)',
+    errorHover: 'var(--sfa-error-hover, #FF8282)',
+    errorLight: 'var(--sfa-error-light, #FEF0F0)',
+    success: 'var(--sfa-success, #A3C848)',
+    warning: 'var(--sfa-warning, #F2B45E)',
+    white: '#FFFFFF',
+    black: '#000000',
+    textPrimary: 'var(--sfa-text-primary, #313542)',
+    textSecondary: 'var(--sfa-text-secondary, #838A98)',
+    textMuted: 'var(--sfa-text-muted, #ACB0BA)',
+    textPlaceholder: 'var(--sfa-text-placeholder, #C1C1C1)',
+    border: 'var(--sfa-border, #D6D9DD)',
+    borderLight: 'var(--sfa-border-light, #F2F2F2)',
+    divider: 'var(--sfa-divider, #F2F2F2)',
+    bgDefault: 'var(--sfa-bg-default, #F7F8FA)',
+    bgSurface: 'var(--sfa-bg-surface, #FFFFFF)',
+    bgHover: 'var(--sfa-bg-hover, rgba(0, 0, 0, 0.03))',
+    bgDisabled: 'var(--sfa-bg-disabled, rgba(0, 0, 0, 0.1))',
+};
+export const font = {
+    family: "var(--sfa-font-family, 'Noto Sans JP', 'Roboto', 'Helvetica', 'Arial', sans-serif)",
+    sizeXs: 11,
+    sizeSm: 12,
+    sizeMd: 13,
+    sizeLg: 14,
+    sizeXl: 16,
+    sizeTitle: 18,
+    weightRegular: 400,
+    weightMedium: 700,
+};
+export const space = {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+};
+export const radius = {
+    sm: 4,
+    md: 4,
+};
+export const baseContainerStyle = {
+    fontFamily: font.family,
+    color: color.textPrimary,
+    fontSize: font.sizeLg,
+};
+export const baseButtonStyle = {
+    fontFamily: font.family,
+    fontSize: font.sizeMd,
+    fontWeight: font.weightRegular,
+    borderRadius: radius.sm,
+    cursor: 'pointer',
+    textTransform: 'none',
+    boxShadow: 'none',
+    lineHeight: '20px',
+    transition: '0.2s',
+};

package/src/lib/version.d.ts

@@ -0,0 +1 @@
+export declare const SFA_KIT_VERSION = "1.6.0";

package/src/lib/version.js

@@ -0,0 +1 @@
+export const SFA_KIT_VERSION = "1.6.0";