starlight-fsharp-oracle 0.1.0

package/packages/FSharp.Oracle.Schema/Schema.fs

@@ -0,0 +1,454 @@
+module FSharp.Oracle.Schema
+
+// ---------------------------------------------------------------------------
+// XML doc comment payloads
+// ---------------------------------------------------------------------------
+
+#nowarn 40
+
+type XmlDocParam =
+    {
+        Name: string
+        Doc: string
+    }
+
+type XmlDoc =
+    {
+        Summary: string option
+        Remarks: string option
+        Returns: string option
+        Params: XmlDocParam list
+        Examples: string list
+    }
+
+/// Whether an API is obsolete and, if so, whether a custom message was supplied.
+[<RequireQualifiedAccess>]
+type ObsoleteInfo =
+    | Active
+    | Deprecated
+    | DeprecatedWithMessage of string
+
+// ---------------------------------------------------------------------------
+// Signature AST
+// ---------------------------------------------------------------------------
+
+[<RequireQualifiedAccess>]
+type TextNode =
+    /// Plain identifier, e.g. "string", "int", "unit".
+    | Text of string
+    /// Named type with its full name for link generation, e.g. ("Option", "Microsoft.FSharp.Core.FSharpOption`1").
+    /// The url field is the pre-computed page URL (slugified, with output base prefix).
+    | TypeRef of name: string * fullName: string * url: string
+    /// Generic type variable, e.g. "T" (the tick is implied — rendered as 'T).
+    | TypeVar of string
+    /// F# keyword, e.g. "val", "type".
+    | Keyword of string
+    | LeftBrace
+    | RightBrace
+    | Equal
+    | Arrow
+    | Tick
+    | Space
+    | Spaces of int
+    | Comma
+    | Colon
+    | Dot
+    | LeftParen
+    | RightParen
+    | LessThan
+    | GreaterThan
+    /// Tuple separator (*).
+    | Star
+    /// Grouping node — a flat list of child nodes.
+    | Node of nodes: TextNode list
+    | NewLine
+    | OpenTag of string
+    | CloseTag of string
+    | OpenTagWithClass of string * string
+    /// An inline hyperlink; href is used as-is (supports page-local `#anchor` refs).
+    | Anchor of text: string * href: string
+    | AnchoredProperty of text: string * href: string
+    /// An inline hyperlink styled as a keyword (e.g. `new` in a constructor declaration).
+    | AnchoredKeyword of text: string * href: string
+
+    member this.TrimStart() =
+        let isWhitespace =
+            function
+            | Space
+            | Spaces _
+            | NewLine -> true
+            | _ -> false
+
+        match this with
+        | Space
+        | Spaces _
+        | NewLine -> Node []
+        | Node nodes -> nodes |> List.skipWhile isWhitespace |> Node
+        | _ -> this
+
+// ---------------------------------------------------------------------------
+// Parameters
+// ---------------------------------------------------------------------------
+
+type Parameter =
+    {
+        Name: string
+        Type: TextNode
+        /// Signature line without column alignment: `\n    name : type`
+        Declaration: TextNode
+        /// Signature line with colon aligned to the common column: `\n    name   : type`
+        AlignedDeclaration: TextNode
+    }
+
+// ---------------------------------------------------------------------------
+// Module-level functions and values
+// ---------------------------------------------------------------------------
+
+type Function =
+    {
+        Name: string
+        FullName: string
+        Signature: TextNode
+        /// Curried parameter groups. Each outer list is a curried group;
+        /// each inner list holds the parameters within that group (tupled parameters).
+        Parameters: Parameter list list
+        /// First line without column alignment: `val name :`
+        Declaration: TextNode
+        /// First line with colon aligned to the common column: `val name   :`
+        AlignedDeclaration: TextNode
+        /// Generic parameters with constraints, e.g. `<\'T when \'T : comparison>`.
+        GenericParameters: TextNode option
+        /// Pre-formatted return type with contextual prefix.
+        /// With parameters: `\n    -> returnType`
+        /// Without parameters: ` returnType`
+        ReturnType: TextNode
+        XmlDoc: XmlDoc
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+type Value =
+    {
+        Name: string
+        FullName: string
+        Signature: TextNode
+        /// Pre-formatted signature line: `val name : type`
+        Declaration: TextNode
+        /// Generic parameters with constraints, e.g. `<\'T when \'T : comparison>`.
+        GenericParameters: TextNode option
+        XmlDoc: XmlDoc
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+// ---------------------------------------------------------------------------
+// Entity members (methods, properties, constructors)
+// ---------------------------------------------------------------------------
+
+[<RequireQualifiedAccess>]
+type MemberKind =
+    | Method
+    | Property
+    | Constructor
+    | Operator
+
+type Member =
+    {
+        Kind: MemberKind
+        Name: string
+        FullName: string
+        /// Curried parameter groups. Each outer list is a curried group;
+        /// each inner list holds the parameters within that group (tupled parameters).
+        Parameters: Parameter list list
+        /// The return type of the member (property type, method return type, or constructed type for constructors).
+        ReturnType: TextNode
+        /// Pre-formatted signature line for the DocEntry slot,
+        /// e.g. `member Add : other : Vector -> Vector` or `property Length : float with get`.
+        Declaration: TextNode
+        /// Generic parameters with constraints, e.g. `<\'T when \'T : comparison>`.
+        GenericParameters: TextNode option
+        XmlDoc: XmlDoc
+        IsStatic: bool
+        /// True for `abstract member` declarations (interface members and abstract class members).
+        IsAbstract: bool
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+// ---------------------------------------------------------------------------
+// Record fields
+// ---------------------------------------------------------------------------
+
+type Field =
+    {
+        Name: string
+        Type: TextNode
+        XmlDoc: XmlDoc
+        /// Pre-formatted signature: `field1 : type`
+        Declaration: TextNode
+    }
+
+    /// Pre-formatted signature: `val field1 : type`
+    member this.Signature =
+        TextNode.Node
+            [
+                TextNode.Keyword "val"
+                TextNode.Space
+                this.Declaration
+            ]
+
+// ---------------------------------------------------------------------------
+// Union cases
+// ---------------------------------------------------------------------------
+
+type UnionCase =
+    {
+        Name: string
+        FullName: string
+        Fields: Field list
+        XmlDoc: XmlDoc
+        /// Pre-formatted signature: `| Name of field1: type1 * field2: type2`
+        Declaration: TextNode
+    }
+
+// ---------------------------------------------------------------------------
+// Entities (types)
+// ---------------------------------------------------------------------------
+
+type RecordEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Fields: Field list
+        Members: Member list
+        /// Pre-formatted full type declaration: `type Name =\n    { field1 : t1\n      ... }`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type UnionEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Cases: UnionCase list
+        Members: Member list
+        /// Pre-formatted full type declaration with anchor links on case names.
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type AbbrevEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        /// The abbreviated type (right-hand side only).
+        Signature: TextNode
+        /// Pre-formatted full declaration: `type Name = abbreviatedType`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type ClassEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Members: Member list
+        /// Pre-formatted full type declaration with member signatures.
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type InterfaceEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Members: Member list
+        /// Pre-formatted full type declaration with member signatures.
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type EnumEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Fields: Field list
+        /// Pre-formatted full type declaration: `type Name =\n    | Case1\n    | ...`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+        IsStruct: bool
+    }
+
+type MeasureEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        /// Pre-formatted declaration: `[<Measure>] type Name`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+type ExceptionEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        Fields: Field list
+        /// Pre-formatted declaration: `exception Name of field1: type1 * field2: type2`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+type DelegateEntity =
+    {
+        Name: string
+        FullName: string
+        XmlDoc: XmlDoc
+        /// Pre-formatted signature of the Invoke method.
+        Signature: TextNode
+        /// Pre-formatted declaration: `type Name = delegate of ... -> ...`
+        Declaration: TextNode
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+[<RequireQualifiedAccess>]
+type Entity =
+    | Record of RecordEntity
+    | Union of UnionEntity
+    | Abbrev of AbbrevEntity
+    | Class of ClassEntity
+    | Interface of InterfaceEntity
+    | Enum of EnumEntity
+    | Measure of MeasureEntity
+    | Exception of ExceptionEntity
+    | Delegate of DelegateEntity
+
+    member this.Name =
+        match this with
+        | Record e -> e.Name
+        | Union e -> e.Name
+        | Abbrev e -> e.Name
+        | Class e -> e.Name
+        | Interface e -> e.Name
+        | Enum e -> e.Name
+        | Measure e -> e.Name
+        | Exception e -> e.Name
+        | Delegate e -> e.Name
+
+    member this.FullName =
+        match this with
+        | Record e -> e.FullName
+        | Union e -> e.FullName
+        | Abbrev e -> e.FullName
+        | Class e -> e.FullName
+        | Interface e -> e.FullName
+        | Enum e -> e.FullName
+        | Measure e -> e.FullName
+        | Exception e -> e.FullName
+        | Delegate e -> e.FullName
+
+    member this.XmlDoc =
+        match this with
+        | Record e -> e.XmlDoc
+        | Union e -> e.XmlDoc
+        | Abbrev e -> e.XmlDoc
+        | Class e -> e.XmlDoc
+        | Interface e -> e.XmlDoc
+        | Enum e -> e.XmlDoc
+        | Measure e -> e.XmlDoc
+        | Exception e -> e.XmlDoc
+        | Delegate e -> e.XmlDoc
+
+    member this.Declaration =
+        match this with
+        | Record e -> e.Declaration
+        | Union e -> e.Declaration
+        | Abbrev e -> e.Declaration
+        | Class e -> e.Declaration
+        | Interface e -> e.Declaration
+        | Enum e -> e.Declaration
+        | Measure e -> e.Declaration
+        | Exception e -> e.Declaration
+        | Delegate e -> e.Declaration
+
+    member this.ObsoleteInfo =
+        match this with
+        | Record e -> e.ObsoleteInfo
+        | Union e -> e.ObsoleteInfo
+        | Abbrev e -> e.ObsoleteInfo
+        | Class e -> e.ObsoleteInfo
+        | Interface e -> e.ObsoleteInfo
+        | Enum e -> e.ObsoleteInfo
+        | Measure e -> e.ObsoleteInfo
+        | Exception e -> e.ObsoleteInfo
+        | Delegate e -> e.ObsoleteInfo
+
+    member this.IsStruct =
+        match this with
+        | Record e -> e.IsStruct
+        | Union e -> e.IsStruct
+        | Abbrev e -> e.IsStruct
+        | Class e -> e.IsStruct
+        | Interface e -> e.IsStruct
+        | Enum e -> e.IsStruct
+        | Measure _ -> false
+        | Exception _ -> false
+        | Delegate _ -> false
+
+// ---------------------------------------------------------------------------
+// Modules
+// ---------------------------------------------------------------------------
+
+type Module =
+    {
+        Name: string
+        FullName: string
+        /// The parent namespace, Encode.g. "Encode.Geometry" for "Encode.Geometry.Points".
+        /// Empty string for root-level modules with no Encode.
+        Namespace: string
+        XmlDoc: string option
+        Entities: Entity list
+        Functions: Function list
+        Values: Value list
+        /// True for synthetic modules that carry bare namespace-level types.
+        /// The plugin generates individual entity pages from these rather than a module Encode.
+        IsSynthetic: bool
+        ObsoleteInfo: ObsoleteInfo
+    }
+
+// ---------------------------------------------------------------------------
+// Namespaces
+// ---------------------------------------------------------------------------
+
+type Namespace =
+    {
+        /// Short display name, e.g. "global", "Reference", "Geometry".
+        Name: string
+        /// Fully-qualified name, e.g. "", "Reference", "Reference.Geometry".
+        FullName: string
+    }
+
+// ---------------------------------------------------------------------------
+// Assemblies — top-level root
+// ---------------------------------------------------------------------------
+
+type Assembly =
+    {
+        Name: string
+        Namespaces: Namespace list
+        Modules: Module list
+    }
+
+type Root =
+    {
+        Assemblies: Assembly list
+    }

package/packages/Starlight.FSharp.Oracle/components/DocEntry.astro

@@ -0,0 +1,256 @@
+---
+import { Aside } from "@astrojs/starlight/components";
+
+interface Props {
+    open?: boolean;
+    name: string;
+    obsolete?: boolean;
+    obsoleteMessage?: string;
+}
+
+const { open = false, name, obsolete = false, obsoleteMessage } = Astro.props;
+---
+
+<div class="collapsible" data-open={open}>
+    <div
+        class="collapsible__trigger"
+        aria-expanded={open ? "true" : "false"}
+        role="button"
+    >
+        <h2 id={name} class="sr-only">{name}</h2>
+        <span class="not-content">
+            <slot name="signature" />
+        </span>
+        {obsolete && <span class="deprecated-badge">Deprecated</span>}
+        <div class="collapsible__icon">
+            <svg
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                xmlns="http://www.w3.org/2000/svg"
+            >
+                <path
+                    d="M10.5858 6.34317L12 4.92896L19.0711 12L12 19.0711L10.5858 17.6569L16.2427 12L10.5858 6.34317Z"
+                    fill="currentColor"></path>
+            </svg>
+        </div>
+        <a
+            href={`#${name}`}
+            class="collapsible__anchor-link"
+            aria-label={`Permalink to ${name}`}
+            title={`Permalink to ${name}`}
+            tabindex="-1"
+        >
+            <svg
+                width="24"
+                height="24"
+                viewBox="0 0 24 24"
+                fill="none"
+                xmlns="http://www.w3.org/2000/svg"
+            >
+                <path
+                    d="M14.8284 12L16.2426 13.4142L19.071 10.5858C20.6331 9.02365 20.6331 6.49099 19.071 4.9289C17.509 3.3668 14.9763 3.3668 13.4142 4.9289L10.5858 7.75732L12 9.17154L14.8284 6.34311C15.6095 5.56206 16.8758 5.56206 17.6568 6.34311C18.4379 7.12416 18.4379 8.39049 17.6568 9.17154L14.8284 12Z"
+                    fill="currentColor"></path>
+                <path
+                    d="M12 14.8285L13.4142 16.2427L10.5858 19.0711C9.02372 20.6332 6.49106 20.6332 4.92896 19.0711C3.36686 17.509 3.36686 14.9764 4.92896 13.4143L7.75739 10.5858L9.1716 12L6.34317 14.8285C5.56212 15.6095 5.56212 16.8758 6.34317 17.6569C7.12422 18.4379 8.39055 18.4379 9.1716 17.6569L12 14.8285Z"
+                    fill="currentColor"></path>
+                <path
+                    d="M14.8285 10.5857C15.219 10.1952 15.219 9.56199 14.8285 9.17147C14.4379 8.78094 13.8048 8.78094 13.4142 9.17147L9.1716 13.4141C8.78107 13.8046 8.78107 14.4378 9.1716 14.8283C9.56212 15.2188 10.1953 15.2188 10.5858 14.8283L14.8285 10.5857Z"
+                    fill="currentColor"></path>
+            </svg>
+        </a>
+    </div>
+    <div class="collapsible__content" role="region" hidden={!open}>
+        {
+            obsolete && (
+                <Aside type="caution" title="Deprecated">
+                    {obsoleteMessage}
+                </Aside>
+            )
+        }
+        <slot />
+    </div>
+</div>
+
+<style>
+    .collapsible {
+        --fo-collapsible-border-raduis: 6px;
+        /*
+            Trying to use Starlight colors for better integration
+            If needed, we can revisit this and add specific colors for the collapsible component
+        */
+        --fo-collapsible-primary-color: var(--sl-color-gray-6);
+        --fo-collapsible-secondary-color: var(--sl-color-gray-7);
+    }
+
+    :global([data-theme="dark"]) .collapsible {
+        --fo-collapsible-primary-color: var(--sl-color-gray-5);
+        --fo-collapsible-secondary-color: var(--sl-color-gray-6);
+    }
+
+    .collapsible__trigger {
+        width: 100%;
+        background-color: transparent;
+        padding: 1rem;
+        cursor: pointer;
+        text-align: left;
+        transition: background 0.15s;
+        position: relative;
+        border-radius: var(--fo-collapsible-border-raduis);
+    }
+
+    .collapsible__trigger:hover {
+        background: var(--fo-collapsible-secondary-color);
+    }
+
+    .collapsible__icon {
+        transition: transform 0.2s ease;
+        position: absolute;
+        left: -1.5rem;
+        top: 1rem;
+        display: flex;
+    }
+
+    .collapsible__anchor-link {
+        position: absolute;
+        left: -3rem;
+        top: 1rem;
+        text-decoration: none;
+        color: var(--sl-color-gray-3);
+        opacity: 0;
+        /* delayed fade-out: wait 400ms before fading over 200ms */
+        transition: opacity 0.2s 0.4s;
+    }
+
+    .collapsible:hover .collapsible__anchor-link {
+        opacity: 0.75;
+        /* fast fade-in on hover, no delay */
+        transition: opacity 0.15s;
+    }
+
+    @keyframes collapsible-flash {
+        50% {
+            background-color: var(--sl-color-accent-low);
+        }
+    }
+
+    .collapsible__trigger[data-flash] {
+        animation: collapsible-flash 0.75s ease;
+        animation-iteration-count: 2;
+    }
+
+    .collapsible[data-open="true"] .collapsible__trigger {
+        border-radius: var(--fo-collapsible-border-raduis)
+            var(--fo-collapsible-border-raduis) 0 0;
+        background-color: var(--fo-collapsible-primary-color);
+    }
+
+    .collapsible[data-open="true"] .collapsible__icon {
+        transform: rotate(90deg);
+    }
+
+    .collapsible__content {
+        margin-top: 0.5rem;
+        padding: 1rem;
+        background-color: var(--fo-collapsible-secondary-color);
+        border-radius: 0 0 var(--fo-collapsible-border-raduis)
+            var(--fo-collapsible-border-raduis);
+    }
+
+    .collapsible__content[hidden] {
+        display: none;
+    }
+
+    .deprecated-badge {
+        position: absolute;
+        top: 1rem;
+        right: 1rem;
+        background-color: var(--sl-color-orange-low);
+        color: var(--sl-color-orange-high);
+        font-size: 0.75em;
+        padding: 0.15em 0.5em;
+        border-radius: 4px;
+        font-weight: 600;
+    }
+
+    .sr-only {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+    }
+</style>
+
+<script>
+    const toggleCollapsible = (el: HTMLElement, isOpen: boolean) => {
+        const trigger = el.querySelector(".collapsible__trigger")!;
+        const content = el.querySelector<HTMLElement>(".collapsible__content")!;
+        const newState = String(!isOpen);
+        el.classList.toggle("is-open", !isOpen);
+        el.dataset["open"] = newState;
+        trigger.setAttribute("aria-expanded", newState);
+        content.hidden = isOpen;
+    };
+
+    document.querySelectorAll<HTMLElement>(".collapsible").forEach((el) => {
+        const trigger = el.querySelector<HTMLElement>(".collapsible__trigger")!;
+
+        trigger.addEventListener("click", (e) => {
+            // Don't toggle when clicking the anchor link
+            if ((e.target as HTMLElement).closest(".collapsible__anchor-link"))
+                return;
+            const isOpen = el.dataset["open"] === "true";
+            toggleCollapsible(el, isOpen);
+        });
+    });
+
+    function flashTrigger(collapsible: HTMLElement) {
+        const trigger = collapsible.querySelector<HTMLElement>(
+            ".collapsible__trigger",
+        )!;
+        trigger.removeAttribute("data-flash");
+        void trigger.offsetWidth; // force reflow to restart animation
+        trigger.setAttribute("data-flash", "");
+        trigger.addEventListener(
+            "animationend",
+            () => trigger.removeAttribute("data-flash"),
+            { once: true },
+        );
+    }
+
+    function openCollapsibleForHash(hash: string) {
+        if (!hash) return;
+        const target = document.getElementById(hash);
+        if (!target) return;
+        const collapsible = target.closest<HTMLElement>(".collapsible");
+        if (!collapsible) return;
+        if (collapsible.dataset["open"] !== "true") {
+            toggleCollapsible(collapsible, false);
+        }
+        collapsible.scrollIntoView({ behavior: "instant", block: "start" });
+        flashTrigger(collapsible);
+    }
+
+    openCollapsibleForHash(window.location.hash.slice(1));
+
+    let ignoreNextHashChange = false;
+
+    document
+        .querySelectorAll<HTMLElement>(".collapsible__anchor-link")
+        .forEach((link) => {
+            link.addEventListener("click", () => {
+                ignoreNextHashChange = true;
+            });
+        });
+
+    window.addEventListener("hashchange", () => {
+        if (ignoreNextHashChange) {
+            ignoreNextHashChange = false;
+            return;
+        }
+        openCollapsibleForHash(window.location.hash.slice(1));
+    });
+</script>