build_tools.name_renderer.render
================================

.. py:module:: build_tools.name_renderer.render

.. autoapi-nested-parse::

   Name rendering for human readability.

   This module provides pure presentation functions for rendering names.
   It is a "presentation lens" - deterministic, reversible, and side-effect free.

   Key Design Principles:
       - Does NOT influence generation, selection, or policy
       - All operations are deterministic and reversible
       - No file I/O, no global state, no hidden configuration
       - Safe to remove or replace without affecting any outputs

   The renderer improves human readability only. If a name looks "wrong",
   the correct fix is policy or selection, not rendering.



Attributes
----------

.. autoapisummary::

   build_tools.name_renderer.render.StyleType
   build_tools.name_renderer.render.AVAILABLE_STYLES


Functions
---------

.. autoapisummary::

   build_tools.name_renderer.render.render
   build_tools.name_renderer.render.render_full_name
   build_tools.name_renderer.render.get_available_styles
   build_tools.name_renderer.render.get_style_description


Module Contents
---------------

.. py:data:: StyleType

.. py:data:: AVAILABLE_STYLES
   :type:  list[str]
   :value: ['title', 'upper', 'lower']


.. py:function:: render(name, name_class, *, style = 'title')

   Render a name for human display.

   Applies presentation styling to a raw name without modifying
   its structure or content. The name_class parameter is available
   for future name-class-aware rendering rules.

   :param name: Raw name string (typically lowercase from selector)
   :param name_class: Name class used for selection (first_name, last_name, etc.)
                      Currently unused but reserved for future styling rules.
   :param style: Presentation style to apply:
                 - "title": Title Case (default) - "orma" -> "Orma"
                 - "upper": UPPERCASE - "orma" -> "ORMA"
                 - "lower": lowercase - "Orma" -> "orma"

   :returns: Rendered name string with styling applied.
             Empty string if input is empty.

   .. admonition:: Examples

      >>> render("orma", "first_name")
      'Orma'
      >>> render("striden", "last_name", style="upper")
      'STRIDEN'
      >>> render("ORMA", "first_name", style="lower")
      'orma'

   .. note::

      The name_class parameter is intentionally unused in this initial
      implementation. It provides a hook for future name-class-aware
      styling (e.g., organisations in CAPS, first names in Title Case).


.. py:function:: render_full_name(first, last, *, style = 'title')

   Combine and render a full name (first + last).

   Creates a properly formatted full name by combining first and last
   name components with appropriate spacing and styling.

   :param first: First name (raw string, typically lowercase)
   :param last: Last name (raw string, typically lowercase)
   :param style: Presentation style to apply to both names:
                 - "title": Title Case (default)
                 - "upper": UPPERCASE
                 - "lower": lowercase

   :returns: Combined and rendered full name.
             Handles missing components gracefully (returns just the present name).
             Returns empty string if both inputs are empty.

   .. admonition:: Examples

      >>> render_full_name("orma", "striden")
      'Orma Striden'
      >>> render_full_name("orma", "striden", style="upper")
      'ORMA STRIDEN'
      >>> render_full_name("orma", "")
      'Orma'
      >>> render_full_name("", "striden")
      'Striden'

   .. note::

      This function is designed for the common "FirstName LastName"
      pattern. For more complex name structures (middle names, suffixes),
      consider extending with additional parameters.


.. py:function:: get_available_styles()

   Return list of available rendering styles.

   Provides the list of valid style names that can be passed
   to render() and render_full_name().

   :returns: ["title", "upper", "lower"]
   :rtype: List of style names

   .. admonition:: Example

      >>> get_available_styles()
      ['title', 'upper', 'lower']


.. py:function:: get_style_description(style)

   Get human-readable description of a rendering style.

   Useful for UI display when showing style options to users.

   :param style: Style name (title, upper, lower)

   :returns: Human-readable description of the style.
             Returns "Unknown style" for invalid inputs.

   .. admonition:: Examples

      >>> get_style_description("title")
      'Title Case (Orma)'
      >>> get_style_description("upper")
      'UPPERCASE (ORMA)'