xnano.fields

def Field(
    default: Any = UNSET,
    *,
    default_factory: Callable[[], Any] | None = None,
    state: bool = False,
    strict: bool = False,
    init: bool = True,
    visible: bool | None = None,
    modifiers: Sequence[types.CharacterModifier] | None = None,
    foreground: ColorLike | None = None,
    color: ColorLike | None = _COLOR_UNSET,
    background: ColorLike | None = None,
    fill: bool | None = None,
    width: SizingLike | None = None,
    height: SizingLike | None = None,
    gap: int | None = None,
    direction: types.Direction | None = None,
    horizontal_align: area.Alignment | None = None,
    vertical_align: area.VerticalAlignment | None = None,
    border: types.Border | None = None,
    border_sides: Sequence[types.Side] | None = None,
    border_color: ColorLike | None = None,
    title: str | None = None,
    title_position: FrameTitlePosition | None = None,
    padding: area.PaddingLike | None = None,
    margin: area.PaddingLike | None = None,
    z: int | None = None,
    overlay: bool = False,
    slide: Sequence[types.Axis] | None = None,
    group: str | None = None,
    autofocus: bool | None = None,
    scroll: types.ScrollLike | None = None,
    wireframe: bool | None = None,
    class_name: ClassNameLike | None = None,
    align: area.Alignment | None = None,
) -> GridFieldInfo:
    """Create a new grid field info instance.

    Args:
        default: Static default value for this field.
        default_factory: Callable that produces the default value each time an instance is created.
        state: Whether this field is a stateful field (does not ever represent renderable content).
        strict: When ``True`` and this field is a state field, assignments are validated
            against the field's type annotation using ``pydantic_core``.
        init: Whether this field should be included within the constructor of it's parent grid class.
        visible: Whether this field is visible on the live terminal display.
        modifiers: Modifiers to apply to all characters within this field. This can be a list
            including "bold", "dim", "italic", "underline", "slow_blink", "rapid_blink",
            "reversed".
        foreground: The foreground color of content within this field.
        color: Deprecated alias for ``foreground``; passing it emits a
            ``DeprecationWarning`` and sets the foreground.
        background: The background color of this field. Fills the whole slot by
            default when set (see ``fill``); also fills the framed content area
            when the field defines border/title/padding chrome.
        fill: Whether ``background`` fills the whole slot. ``None`` fills when a
            background is set; ``True`` forces a full-slot fill; ``False`` paints
            the color only behind text glyphs.
        width: Horizontal extent sizing (``10``, ``"50%"``, ``"1fr"``, ``"fit"``,
            or a ``Sizing``). Drives the split constraint in horizontal layouts;
            shrinks the slot along the cross axis otherwise.
        height: Vertical extent sizing (``3``, ``"50%"``, ``"1fr"``, ``"fit"``,
            or a ``Sizing``). Drives the split constraint in vertical layouts;
            shrinks the slot along the cross axis otherwise.
        gap: The gap between fields in this field or area.
        direction: The direction in which content within this field or area should be laid out.
        horizontal_align: The horizontal alignment of content within this
            field's area.
        vertical_align: The vertical alignment of content within this
            field's area.
        border: A border style to be applied onto the outer frame of the rectangular area this
            field occupies.
        border_sides: The sides of the border to be applied onto the outer frame of the area
            this field occupies.
        border_color: The color of this field's border, if one is set.
        title: A title to be displayed around the outer frame of this field's area.
        title_position: The alignment of the title within the outer frame of this
            field's area.
        padding: The padding to be applied around the content area of this field.
        margin: The margin to be applied around the outer area of this field.
        z: Layering order for this field's slot relative to its grid. ``None``
            inherits the grid's own ``z``; an explicit value stacks the field's
            whole subtree (text, component, or nested grid) above or below its
            siblings and is additive with the grid's ``z``.
        overlay: Float this field over the grid's content area (centered, sized
            by ``width``/``height``) instead of giving it a layout slot. Pair
            with a higher ``z`` for a popup or modal over the panels behind it.
        slide: The axes along which this field may slide within its parent grid.
        class_name: Tailwind CSS classes styling this field — a space-separated
            string or a sequence of class tokens. Classes are lowered into the
            standard field attributes (see ``xnano.tailwind``); an explicit
            keyword argument always overrides a class-derived value. Classes
            with no terminal equivalent are ignored by the terminal backend and
            emitted verbatim by the web backend.

    Returns:
        A new ``GridFieldInfo`` instance with all display/layout metadata,
        including the normalized ``class_name`` tokens.
    """
    if color is not _COLOR_UNSET:
        warn_color_alias(stacklevel=2)
        if foreground is None:
            foreground = color
    horizontal_align = resolve_renamed_alias(
        horizontal_align,
        align,
        old="align",
        new="horizontal_align",
        stacklevel=2,
    )
    tokens: tuple[str, ...] | None = None
    if class_name is not None:
        from xnano.tailwind import (
            normalize_tailwind_classes,
            resolve_tailwind_classes,
        )

        tokens = normalize_tailwind_classes(class_name)
        resolved = resolve_tailwind_classes(tokens)
        if foreground is None:
            foreground = resolved.foreground
        if background is None:
            background = resolved.background
        if border is None:
            border = resolved.border
        if border_color is None:
            border_color = resolved.border_color
        if border_sides is None:
            border_sides = resolved.border_sides
        if padding is None:
            padding = resolved.padding
        if margin is None:
            margin = resolved.margin
        if gap is None:
            gap = resolved.gap
        if width is None:
            width = resolved.width
        if height is None:
            height = resolved.height
        if modifiers is None and resolved.modifiers:
            modifiers = resolved.modifiers
        if horizontal_align is None:
            horizontal_align = resolved.horizontal_align
        if direction is None:
            direction = resolved.direction

    return GridFieldInfo(
        default=default,
        default_factory=default_factory,
        state=state,
        strict=strict,
        init=init,
        visible=visible,
        foreground=foreground,
        modifiers=modifiers,
        background=background,
        fill=fill,
        width=Sizing.parse(width),
        height=Sizing.parse(height),
        gap=gap,
        direction=direction,
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        border=border,
        border_sides=border_sides,
        border_color=border_color,
        title=title,
        title_position=title_position,
        padding=padding,
        margin=margin,
        z=z,
        overlay=overlay,
        slide=_normalize_slide_axes(slide),
        group=group,
        autofocus=autofocus,
        scroll=scroll,
        wireframe=wireframe,
        class_name=tokens,
    )  # type: ignore[return-value]