001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bean.html5;
018
019import org.apache.juneau.marshall.*;
020
021/**
022 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#the-label-element">&lt;label&gt;</a>
023 * element.
024 *
025 * <p>
026 * The label element represents a caption for a form control. It provides a programmatic association
027 * between the label and the form control, improving accessibility and user experience. When a label
028 * is associated with a form control, clicking the label will focus or activate the control.
029 *
030 * <h5 class='section'>Examples:</h5>
031 * <p class='bcode w800'>
032 *    <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*;
033 *
034 *    <jc>// Label with explicit association</jc>
035 *    Label <jv>label1</jv> = <jsm>label</jsm>(<js>"Username:"</js>)
036 *       .for_(<js>"username"</js>);
037 *
038 *    <jc>// Label wrapping form control</jc>
039 *    Label <jv>label2</jv> = <jsm>label</jsm>(
040 *       <jsm>input</jsm>(<js>"checkbox"</js>).name(<js>"agree"</js>),
041 *       <jsm>span</jsm>(<js>"I agree to the terms and conditions"</js>)
042 *    );
043 *
044 *    <jc>// Label with form association</jc>
045 *    Label <jv>label3</jv> = <jsm>label</jsm>(<js>"Email Address:"</js>)
046 *       .for_(<js>"email"</js>)
047 *       .form(<js>"contactForm"</js>);
048 *
049 *    <jc>// Label with styling</jc>
050 *    Label <jv>label4</jv> = <jsm>label</jsm>(<js>"Password:"</js>)
051 *       .for_(<js>"password"</js>)
052 *       .class_(<js>"required"</js>);
053 * </p>
054 *
055 * <h5 class='section'>See Also:</h5><ul>
056 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
057 * </ul>
058 */
059@Marshalled(typeName = "label")
060public class Label extends HtmlElementMixed<Label> {
061
062   /**
063    * Creates an empty {@link Label} element.
064    */
065   public Label() {}
066
067   /**
068    * Creates a {@link Label} element with the specified child nodes.
069    *
070    * @param children The child nodes. Must not be <jk>null</jk>.
071    */
072   public Label(Object...children) {
073      children(children);
074   }
075
076   /**
077    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-label-for">for</a> attribute.
078    *
079    * <p>
080    * Associates the label with a form control by specifying the control's ID. This creates
081    * a programmatic relationship between the label and the form control for accessibility.
082    *
083    * <p>
084    * The value should match the ID of a form control element in the same document.
085    *
086    * @param value The ID of the form control to associate with this label. Can be <jk>null</jk> to unset the attribute.
087    * @return This object.
088    */
089   @SuppressWarnings({
090      "java:S100" // Method name uses underscore suffix to avoid Java keyword conflict
091   })
092   public Label for_(String value) {
093      attr("for", value);
094      return this;
095   }
096
097   /**
098    * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute.
099    *
100    * <p>
101    * Associates the label with a form element by specifying the form's ID. This allows the label
102    * to be placed outside the form element while still being part of the form.
103    *
104    * <p>
105    * The value should match the ID of a form element in the same document.
106    *
107    * @param value The ID of the form element to associate with this label. Can be <jk>null</jk> to unset the attribute.
108    * @return This object.
109    */
110   public Label form(String value) {
111      attr("form", value);
112      return this;
113   }
114
115}