@ai-digital-factory/state-flow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 coupleaddagaming@gmail.com. All rights reserved.
+
+State Flow is proprietary software. No license is granted by downloading,
+accessing, or receiving this software or its documentation. All third-party
+use, including personal, noncommercial and commercial use, requires prior
+written permission from the copyright holder. Copying, modifying, distributing,
+sublicensing or incorporating this software into another product also requires
+prior written permission. Request permission at coupleaddagaming@gmail.com.
+
+Any permission granted separately is governed by its written terms. This notice
+does not alter the licenses of third-party dependencies or bundled third-party
+materials; their respective licenses continue to apply.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
+THE COPYRIGHT HOLDER IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+ARISING FROM THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @ai-digital-factory/state-flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React library for flow-style state (states, transitions, and related UI). See repository `CONTEXT.md` for domain vocabulary.
+
+## Application chart authoring (TSX, no React app)
+
+Chart-only projects declare flows as `.tsx` modules using `Flow`, `State`, and `Transition`. They do not install `react` or `@types/react`.
+
+Extend the chart preset (TypeScript requires `jsx` for `.tsx`; the preset supplies it):
+
+```json
+{
+  "extends": "@ai-digital-factory/state-flow/tsconfig.charts.json",
+  "include": ["src/**/*.tsx"]
+}
+```
+
+Or set the same options yourself, including `"types": ["@ai-digital-factory/state-flow/types"]` and `"jsx": "react-jsx"`.
+
+Preview and in-app rendering supply React at runtime via the State Flow CLI or your React consumer.
+
+## License
+
+Proprietary software. All third-party use requires prior written permission from
+coupleaddagaming@gmail.com. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { ReactElement, ReactNode } from 'react';
+import { ApplicationChartDefinition } from '@ai-digital-factory/state-flow-chart';
+export { ApplicationHookContext, DEFAULT_TRANSITION_NAME, DefaultTransitionName, STATE_APPLICATION_HOOK_EXPORT_NAMES, TRANSITION_APPLICATION_HOOK_EXPORT_NAMES, TransitionHookContext } from '@ai-digital-factory/state-flow-chart';
+
+declare function StateFlowPlaceholder(): ReactElement;
+
+type FlowProps = {
+    /** Lowercase kebab-case chart identifier (e.g. `visitor-access`). Enforced by chart check. */
+    name: string;
+    description: string;
+    default: string;
+    children?: ReactNode;
+};
+declare function Flow({ name, description, default: defaultStateName, children, }: FlowProps): ReactElement;
+declare namespace Flow {
+    var displayName: string;
+}
+
+type StateProps = {
+    id?: string;
+    name: string;
+    description: string;
+    children?: ReactNode;
+};
+/** Declares a flow state; rendered by `Flow`, not directly. */
+declare function State(_props: StateProps): null;
+declare namespace State {
+    var displayName: string;
+}
+
+type TransitionProps = {
+    to: string;
+    name: string;
+    description: string;
+    children?: ReactNode;
+};
+/** Declares an allowed transition; rendered by `Flow`, not directly. */
+declare function Transition(_props: TransitionProps): null;
+declare namespace Transition {
+    var displayName: string;
+}
+
+type ApplicationChartRendererProps = {
+    chart: ApplicationChartDefinition;
+};
+declare function ApplicationChartRenderer({ chart, }: ApplicationChartRendererProps): ReactElement;
+
+type ChartPageHeaderProps = {
+    title: string;
+    description: string;
+    /** Lowercase kebab-case chart id; picks a header icon when set. */
+    chartId?: string;
+};
+declare function ChartPageHeader({ title, description, chartId, }: ChartPageHeaderProps): ReactElement;
+
+declare function ChartHeaderIcon({ chartId, }: {
+    chartId?: string;
+}): ReactElement;
+declare function chartNavIcon(chartId: string): string;
+
+type ParsedTransition = {
+    fromId: string;
+    fromName: string;
+    toId: string;
+    toName: string;
+    name: string;
+    description: string;
+};
+type ParsedState = {
+    id: string;
+    name: string;
+    description: string;
+};
+type ParsedChart = {
+    states: ParsedState[];
+    edges: ParsedTransition[];
+    initialId: string;
+};
+
+type DiagramOverviewProps = {
+    svgHtml: string;
+    states: ParsedState[];
+    edges: ParsedTransition[];
+    /** When set, sync zoom, pan, and diagram focus to the page URL query string. */
+    viewPersistenceKey?: string;
+    /** Highlight a transition edge after a guard blocks (simulate). */
+    guardBlockedEdgeIndex?: number | null;
+    /** Stack detail below the diagram, or show state/transition aside (tool viewers). */
+    detailLayout?: "inline" | "split";
+    /** When set with `detailLayout="split"`, pre-select this state in the aside. */
+    initialStateId?: string;
+};
+declare function DiagramOverview({ svgHtml, states, edges, viewPersistenceKey, guardBlockedEdgeIndex, detailLayout, initialStateId, }: DiagramOverviewProps): ReactElement;
+
+/** Forward edges run above the states; return edges run below them. */
+declare function diagramSvg(chart: ParsedChart, title: string, instanceId: string): string;
+
+declare function parseScrollYFromSearch(search: string): number | null;
+declare function mergeScrollYIntoSearch(search: string, scrollY: number): string;
+declare function replaceBrowserUrlSearch(search: string): void;
+
+declare function extractApplicationChartDefinition(node: ReactNode): ApplicationChartDefinition;
+type ApplicationChartComponent = () => ReactNode;
+declare function extractApplicationChartDefinitionFromComponent(component: ApplicationChartComponent): ApplicationChartDefinition;
+
+export { type ApplicationChartComponent, ApplicationChartRenderer, type ApplicationChartRendererProps, ChartHeaderIcon, ChartPageHeader, type ChartPageHeaderProps, DiagramOverview, type DiagramOverviewProps, Flow, type FlowProps, State, StateFlowPlaceholder, type StateProps, Transition, type TransitionProps, chartNavIcon, diagramSvg, extractApplicationChartDefinition, extractApplicationChartDefinitionFromComponent, mergeScrollYIntoSearch, parseScrollYFromSearch, replaceBrowserUrlSearch };