Add text component docs (#3293)

components/copy.rst

@@ -193,6 +193,24 @@ Configuration variables:
 - **name** (**Required**, string): The name of the text sensor.
 - All other options from :ref:`Text Sensor <config-text_sensor>`.
 
+Copy Text
+---------
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    text:
+      - platform: copy
+        source_id: source_text
+        name: "Copy of source_text"
+
+Configuration variables:
+************************
+
+- **source_id** (**Required**, :ref:`config-id`): The text that should be mirrored.
+- **name** (**Required**, string): The name of the number.
+- All other options from :ref:`Text <config-text>`.
+
 See Also
 --------
 

components/index.rst

@@ -27,4 +27,5 @@ Components
     speaker/index
     time/index
     alarm_control_panel/index
+    text/index
     *

components/text/index.rst

@@ -0,0 +1,144 @@
+Text Component
+==============
+
+.. seo::
+    :description: Instructions for setting up text components in ESPHome.
+    :image: folder-open.svg
+
+ESPHome has support for components to create a text entity. A text entity is
+like a ``text_sensor`` that can read a value from a device, but is useful when that value
+can be set by the user/frontend.
+
+.. note::
+
+    Home Assistant Core 2023.11 or higher is required for ESPHome text entities to work.
+
+.. _config-text:
+
+Base Text Configuration
+-----------------------
+
+All texts in ESPHome have a name and an optional icon.
+
+.. code-block:: yaml
+
+    # Example text configuration
+    name: Livingroom Text
+
+    # Optional variables:
+    icon: "mdi:cursor-text"
+
+Configuration variables:
+
+- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
+- **name** (**Required**, string): The name for the text.
+
+  .. note::
+
+      If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
+      you want the text to use that name, you can set ``name: None``.
+
+- **icon** (*Optional*, icon): Manually set the icon to use for the text in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+  Defaults to ``false``.
+- **entity_category** (*Optional*, string): The category of the entity.
+  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
+  for a list of available options. Set to ``""`` to remove the default entity category.
+- **mode** (**Required**, string): Defines how the text should be displayed in the frontend.
+  One of ``text`` or ``password``.
+
+Automations:
+
+- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when a new value is published. See :ref:`text-on_value`.
+
+MQTT Options:
+
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+Text Automation
+---------------
+
+You can access the most recent state of the text in :ref:`lambdas <config-lambda>` using
+``id(text_id).state``.
+
+.. _text-on_value:
+
+``on_value``
+************
+
+This automation will be triggered when a new value is published. In :ref:`Lambdas <config-lambda>`
+you can get the value from the trigger with ``x``.
+
+.. code-block:: yaml
+
+    text:
+      - platform: template
+        # ...
+        on_value:
+          then:
+            - logger.log:
+                format: "%s"
+                args: ["x.c_str()"]
+
+Configuration variables: See :ref:`Automation <automation>`.
+
+.. _text-set_action:
+
+``text.set`` Action
+*******************
+
+This is an :ref:`Action <config-action>` for setting a text state.
+
+.. code-block:: yaml
+
+    - text.set:
+        id: my_text
+        value: "Hello World"
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the text to set.
+- **value** (**Required**, string, :ref:`templatable <config-templatable>`):
+  The value to set the text to.
+
+.. _text-lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can call certain methods on all texts to do some
+advanced stuff (see the full API Reference for more info).
+
+- ``.make_call()``: Make a call for updating the text value.
+
+  .. code-block:: cpp
+
+      // Within lambda, push a value of 42
+      auto call = id(my_text).make_call();
+      call.set_value("Hello World");
+      call.perform();
+
+- ``.state``: Retrieve the current value of the text.
+
+  .. code-block:: cpp
+
+      // For example, create a custom log message when a value is received:
+      ESP_LOGI("main", "Value of my text: %s", id(my_text).state.c_str());
+
+See Also
+--------
+
+- :apiref:`Text <text/text.h>`
+- :apiref:`TextCall <text/text_call.h>`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

components/text/template.rst

@@ -0,0 +1,50 @@
+Template Text
+=============
+
+.. seo::
+    :description: Instructions for setting up template texts with ESPHome.
+    :image: description.svg
+
+The ``template`` text platform allows you to create a text with templated values
+using :ref:`lambdas <config-lambda>`.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    text:
+      - platform: template
+        name: "Template text"
+        optimistic: true
+        min_length: 0
+        max_length: 100
+        mode: text
+
+Configuration variables:
+------------------------
+
+- **min_lenngth** (**Required**, float): The minimum length this text can be.
+- **max_length** (**Required**, float): The maximum length this text can be.
+- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
+  Lambda to be evaluated every update interval to get the current value of the text.
+- **set_action** (*Optional*, :ref:`Action <config-action>`): The action that should
+  be performed when the remote (like Home Assistant's frontend) requests to set the
+  text value. The new value is available to lambdas in the ``x`` variable.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval on which to update the text
+  by executing the ``lambda``. Defaults to ``60s``.
+- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
+  any command sent to the template text will immediately update the reported state.
+  Cannot be used with ``lambda``. Defaults to ``false``.
+- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash.
+  Cannot be used with ``lambda``. Defaults to ``false``.
+- **initial_value** (*Optional*, float): The value to set the state to on setup if not
+  restored with ``restore_value``.
+  Cannot be used with ``lambda``.
+- All other options from :ref:`Text <config-text>`.
+
+
+See Also
+--------
+
+- :ref:`automation`
+- :apiref:`template/text/template_text.h`
+- :ghedit:`Edit`

index.rst

@@ -746,6 +746,14 @@ Lock Components
     Generic Output Lock, components/lock/output, upload.svg, dark-invert
     Template Lock, components/lock/template, description.svg, dark-invert
 
+Text Components
+---------------
+
+.. imgtable::
+
+    Text Core, components/text/index, folder-open.svg, dark-invert
+    Template Text, components/text/template, description.svg, dark-invert
+
 Media Player Components
 -----------------------