api-reference-param-list

use fandhe_frontend_core::{div, text, Node};
use fandhe_frontend_pre_styled_ui::badge::{self, BadgeProps, BadgeVariant};
use fandhe_frontend_pre_styled_ui::code::{self, CodeProps};
use fandhe_frontend_pre_styled_ui::heading::{heading, HeadingLevel, HeadingProps, HeadingSize};
use fandhe_frontend_pre_styled_ui::link::{self, LinkProps};
use fandhe_frontend_pre_styled_ui::recipe::ColorPalette;
use fandhe_frontend_pre_styled_ui::separator::{separator, SeparatorProps};
use fandhe_frontend_pre_styled_ui::text::{self as styled_text, TextProps, TextSize, TextVariant};

/// 架空のクエリパラメータ 1 件（名前・id・href・型・必須か・説明・許可値）。
/// `id`/`href` はアンカーリンクと見出しの対応表の唯一の情報源。
struct Param {
    name: &'static str,
    id: &'static str,
    href: &'static str,
    ty: &'static str,
    required: bool,
    description: &'static str,
    allowed: &'static [&'static str],
}

/// 架空のクエリパラメータ一覧（実在サービスの API 名は含まない）。
const PARAMS: [Param; 4] = [
    Param {
        name: "project_id",
        id: "blocks-api-reference-param-list-project-id",
        href: "#blocks-api-reference-param-list-project-id",
        ty: "string",
        required: true,
        description: "対象プロジェクトの識別子。",
        allowed: &[],
    },
    Param {
        name: "status",
        id: "blocks-api-reference-param-list-status",
        href: "#blocks-api-reference-param-list-status",
        ty: "enum",
        required: true,
        description: "取得対象の状態。",
        allowed: &["active", "archived"],
    },
    Param {
        name: "sort",
        id: "blocks-api-reference-param-list-sort",
        href: "#blocks-api-reference-param-list-sort",
        ty: "enum",
        required: false,
        description: "並び順の基準。",
        allowed: &["created", "updated", "name"],
    },
    Param {
        name: "limit",
        id: "blocks-api-reference-param-list-limit",
        href: "#blocks-api-reference-param-list-limit",
        ty: "integer",
        required: false,
        description: "1 ページあたりの最大件数。",
        allowed: &[],
    },
];

/// 許可値バッジの並び（列挙型の項目のみ出力する）。
fn allowed_values_row(allowed: &[&'static str]) -> Option<Node> {
    if allowed.is_empty() {
        return None;
    }
    let mut children: Vec<Node> = vec![styled_text::text(
        &TextProps {
            variant: TextVariant::Muted,
            size: TextSize::Sm,
            ..TextProps::default()
        },
        vec![],
        vec![text("許可値:")],
    )];
    children.extend(allowed.iter().map(|value| {
        badge::badge(
            &BadgeProps {
                variant: BadgeVariant::Surface,
                ..BadgeProps::default()
            },
            vec![],
            vec![text(*value)],
        )
    }));
    Some(div(
        vec![("data-blocks-api-reference-param-list-values", "")],
        children,
    ))
}

/// パラメータ 1 件分（名前・バッジ行 + 説明 + 任意の許可値行）。
fn param_item(param: &Param) -> Node {
    // `aria-label` に `param.name` を含める。全項目で固定文言にすると
    // スクリーンリーダーのリンク一覧上でどのパラメータへのリンクか
    // 区別できないため（イシュー #3101 レビュー指摘）。
    let anchor_label = format!("{} 項目へのリンク", param.name);
    let mut meta_children: Vec<Node> = vec![
        code::code(&CodeProps::default(), vec![], vec![text(param.name)]),
        link::root(
            param.href,
            &LinkProps::default(),
            vec![
                ("aria-label", anchor_label.as_str()),
                ("data-blocks-api-reference-param-list-anchor", ""),
            ],
            vec![text("#")],
        ),
        badge::badge(
            &BadgeProps {
                variant: BadgeVariant::Outline,
                ..BadgeProps::default()
            },
            vec![],
            vec![text(param.ty)],
        ),
    ];
    if param.required {
        meta_children.push(badge::badge(
            &BadgeProps {
                variant: BadgeVariant::Subtle,
                palette: ColorPalette::Danger,
                ..BadgeProps::default()
            },
            vec![],
            vec![text("必須")],
        ));
    }

    let mut children: Vec<Node> = vec![
        heading(
            HeadingLevel::H4,
            &HeadingProps {
                size: HeadingSize::Md,
                ..HeadingProps::default()
            },
            vec![("id", param.id)],
            meta_children,
        ),
        styled_text::text(&TextProps::default(), vec![], vec![text(param.description)]),
    ];
    if let Some(values_row) = allowed_values_row(param.allowed) {
        children.push(values_row);
    }

    div(
        vec![("data-blocks-api-reference-param-list-item", "")],
        children,
    )
}

/// パラメータ一覧（項目の間にだけ `separator` を置く。末尾には置かない）。
fn param_list() -> Node {
    let mut children: Vec<Node> = Vec::new();
    for (index, param) in PARAMS.iter().enumerate() {
        if index > 0 {
            children.push(separator(&SeparatorProps::default(), vec![]));
        }
        children.push(param_item(param));
    }
    div(
        vec![("data-blocks-api-reference-param-list-list", "")],
        children,
    )
}

/// `api-reference-param-list` の Demo 本体。呼び出しごとに同一の `Node` を
/// 返す純関数。
pub fn demo() -> Node {
    div(
        vec![("data-blocks-api-reference-param-list-layout", "")],
        vec![
            heading(
                HeadingLevel::H3,
                &HeadingProps {
                    size: HeadingSize::Xl2,
                    ..HeadingProps::default()
                },
                vec![],
                vec![text("クエリパラメータ")],
            ),
            styled_text::text(
                &TextProps {
                    variant: TextVariant::Muted,
                    ..TextProps::default()
                },
                vec![],
                vec![text("一覧取得エンドポイントで指定できる条件です。")],
            ),
            param_list(),
        ],
    )
}